atomptr: add direct crate docs instead of relying on doc(include)

development/libs/atomptr/src/lib.rs

@@ -1,5 +1,33 @@
-#![feature(external_doc)]
-#![doc(include = "../README.md")]
+//! A safe, strongly typed (generic) atomic pointer abstraction to build
+//! datastructures, and lock-free algorithms on top of.  Only uses
+//! `libstd`.
+//! 
+//! The standard library contains an `AtomicPtr` type, which by itself
+//! isn't very ergonomic to use, because it deals with raw pointers.  This
+//! library assumes that types can always be heap allocated, wrapping them
+//! in a `Box<T>`, and provides a nicer (and safe!) abstraction for
+//! `std::sync::atomic::AtomicPtr`.  Using this crate is fairely
+//! self-explanatory:
+//! 
+//! ```rust
+//! use atomptr::AtomPtr;
+//! 
+//! struct MyData { name: String }
+//! let data = MyData { name: "Kookie".into() };
+//! 
+//! let a = AtomPtr::new(data);
+//! println!("Name is: {}", a.get_ref().name);
+//! 
+//! let old_ref = a.swap(MyData { name: "Bob".into() });
+//! println!("Name now is: {}, was {}", a.get_ref().name, old_ref.name);
+//! ```
+//! 
+//! Note that the type that is returned by `get_ref` and `swap` is
+//! `Ref<T>`, which means that the old data is not de-allocated after a
+//! swap, before this last reference goes out of scope.  You can of course
+//! always manually call `drop()` on it.
+
+
 
 use std::sync::{
     atomic::{AtomicPtr, Ordering},