From de7edaeb0c5edb44f8020611775d3c5aecf22efd Mon Sep 17 00:00:00 2001
From: Bradlee Speice <bradlee@speice.io>
Date: Sat, 10 Nov 2018 21:36:23 -0500
Subject: [PATCH] Update the docs

---
 qadapt-macro/src/lib.rs | 15 +++++++--------
 src/lib.rs              | 17 +++++++++++++++++
 2 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/qadapt-macro/src/lib.rs b/qadapt-macro/src/lib.rs
index 47512b4..7494913 100644
--- a/qadapt-macro/src/lib.rs
+++ b/qadapt-macro/src/lib.rs
@@ -1,12 +1,8 @@
 //! Helper macros to use with the QADAPT allocator system
 //! 
-//! This crate is unusable on its own, but because `proc_macro` crates
-//! can't export non-proc-macro symbols, we have to go through an extra step
-//! to move these up.
+//! This crate is intended for managing the QADAPT allocator,
+//! and is unusable on its own.
 //! 
-//! Ultimately, this does actually work because we don't need to actually use
-//! references to the underlying functionality here, we just need to know
-//! where they will ultimately end up at.
 // TODO: This causes issues, but I can't track down why
 // #![deny(missing_docs)]
 extern crate proc_macro;
@@ -15,8 +11,11 @@ use proc_macro::TokenTree;
 use proc_macro::TokenStream;
 
 /// Set up the QADAPT allocator to trigger a panic if any allocations happen during
-/// this function. Race conditions between threads are not checked, this macro will
-/// only work as intended in a single-threaded or otherwise synchronized environment.
+/// calls to this function.
+/// 
+/// QADAPT will only track allocations in the thread that calls this function;
+/// if (for example) this function receives the results of an allocation in a
+/// separate thread, QADAPT will not trigger a panic.
 #[proc_macro_attribute]
 pub fn allocate_panic(_attr: TokenStream, item: TokenStream) -> TokenStream {
     let ret = item.clone();
diff --git a/src/lib.rs b/src/lib.rs
index 1b9e6ce..4269192 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,15 @@
+//! The Quick And Dirty Allocation Profiling Tool
+//! 
+//! This allocator is a helper for writing high-performance code that is allocation/drop free;
+//! for functions annotated with `#[allocate_panic]`, QADAPT will detect when allocations/drops
+//! happen during their execution (and execution of any functions they call) and throw a
+//! thread panic if this occurs.
+//! 
+//! Because QADAPT panics on allocation and is rather slow (for an allocator) it is **strongly**
+//! recommended that QADAPT (the allocator) be used only in code tests. Functions annotated with
+//! `#[allocate_panic]` will have no side effects if the QADAPT allocator is not being used,
+//! so the attribute is safe to leave everywhere.
+#![deny(missing_docs)]
 extern crate libc;
 extern crate qadapt_macro;
 extern crate spin;
@@ -18,8 +30,11 @@ thread_local! {
     static PROTECTION_LEVEL: RwLock<u32> = RwLock::new(0);
 }
 
+/// The QADAPT allocator itself
 pub struct QADAPT;
 
+/// Let QADAPT know that we are now entering a protected region and that
+/// panics should be triggered if allocations/drops happen while we are running.
 pub fn enter_protected() {
     if thread::panicking() {
         return
@@ -30,6 +45,8 @@ pub fn enter_protected() {
     }).unwrap_or_else(|_e| ());
 }
 
+/// Let QADAPT know that we are exiting a protected region. Will panic
+/// if we attempt to [`exit_protected`] more times than we [`enter_protected`].
 pub fn exit_protected() {
     if thread::panicking() {
         return