Auto merge of #200 - derekdreery:docs_docs_docs, r=jdm

Add documentation, and the ability to generate documentation.

Multiple changes

 - Add documentation to types & methods in atom.rs
 - Add ability to add documentation to generated types

What I'm trying to achieve with this is
 1. Someone can look at this library and know how to use it without looking at the source code.
 2. Someone who sees the generated types in another library (like html5ever) can just know they are interned strings and not worry too much about the interal details of the internment.

I hope it's useful :)

<!-- Reviewable:start -->
---
This change is [<img src="https://reviewable.io/review_button.svg" height="34" align="absmiddle" alt="Reviewable"/>](https://reviewable.io/reviews/servo/string-cache/200)
<!-- Reviewable:end -->

Author: bors-servo

src/atom.rs

@@ -138,18 +138,36 @@ impl StringCache {
     }
 }
 
+/// A static `PhfStrSet`
+///
+/// This trait is implemented by static sets of interned strings generated using
+/// `string_cache_codegen`, and `EmptyStaticAtomSet` for when strings will be added dynamically.
+///
+/// It is used by the methods of [`Atom`] to check if a string is present in the static set.
+///
+/// [`Atom`]: struct.Atom.html
 pub trait StaticAtomSet {
+    /// Get the location of the static string set in the binary.
     fn get() -> &'static PhfStrSet;
+    /// Get the index of the empty string, which is in every set and is used for `Atom::default`.
     fn empty_string_index() -> u32;
 }
 
+/// A string set created using a [perfect hash function], specifically
+/// [Hash, Displace and Compress].
+///
+/// See the CHD document for the meaning of the struct fields.
+///
+/// [perfect hash function]: https://en.wikipedia.org/wiki/Perfect_hash_function
+/// [Hash, Displace and Compress]: http://cmph.sourceforge.net/papers/esa09.pdf
 pub struct PhfStrSet {
     pub key: u64,
     pub disps: &'static [(u32, u32)],
     pub atoms: &'static [&'static str],
     pub hashes: &'static [u32],
 }
 
+/// An empty static atom set for when only dynamic strings will be added
 pub struct EmptyStaticAtomSet;
 
 impl StaticAtomSet for EmptyStaticAtomSet {
@@ -174,6 +192,10 @@ impl StaticAtomSet for EmptyStaticAtomSet {
 /// Use this if you don’t care about static atoms.
 pub type DefaultAtom = Atom<EmptyStaticAtomSet>;
 
+/// Represents a string that has been interned.
+///
+/// In reality this contains a complex packed datastructure and the methods to extract information
+/// from it, along with type information to tell the compiler which static set it corresponds to.
 pub struct Atom<Static: StaticAtomSet> {
     /// This field is public so that the `atom!()` macros can use it.
     /// You should not otherwise access this field.
@@ -207,6 +229,7 @@ impl<Static: StaticAtomSet> Atom<Static> {
         UnpackedAtom::from_packed(self.unsafe_data)
     }
 
+    /// Get the hash of the string as it is stored in the set.
     pub fn get_hash(&self) -> u32 {
         match unsafe { self.unpack() } {
             Static(index) => {
@@ -441,11 +464,7 @@ impl<Static: StaticAtomSet> Atom<Static> {
         let mut buffer: [u8; 64] = unsafe { mem::uninitialized() };
         if let Some(buffer_prefix) = buffer.get_mut(..s.len()) {
             buffer_prefix.copy_from_slice(s.as_bytes());
-            // FIXME: use from std::str when stable https://github.com/rust-lang/rust/issues/41119
-            pub unsafe fn from_utf8_unchecked_mut(v: &mut [u8]) -> &mut str {
-                mem::transmute(v)
-            }
-            let as_str = unsafe { from_utf8_unchecked_mut(buffer_prefix) };
+            let as_str = unsafe { ::std::str::from_utf8_unchecked_mut(buffer_prefix) };
             f(as_str);
             Atom::from(&*as_str)
         } else {
@@ -455,6 +474,9 @@ impl<Static: StaticAtomSet> Atom<Static> {
         }
     }
 
+    /// Like [`to_ascii_uppercase`].
+    ///
+    /// [`to_ascii_uppercase`]: https://doc.rust-lang.org/std/ascii/trait.AsciiExt.html#tymethod.to_ascii_uppercase
     pub fn to_ascii_uppercase(&self) -> Self {
         for (i, b) in self.bytes().enumerate() {
             if let b'a' ... b'z' = b {
@@ -464,6 +486,9 @@ impl<Static: StaticAtomSet> Atom<Static> {
         self.clone()
     }
 
+    /// Like [`to_ascii_lowercase`].
+    ///
+    /// [`to_ascii_lowercase`]: https://doc.rust-lang.org/std/ascii/trait.AsciiExt.html#tymethod.to_ascii_lowercase
     pub fn to_ascii_lowercase(&self) -> Self {
         for (i, b) in self.bytes().enumerate() {
             if let b'A' ... b'Z' = b {
@@ -473,10 +498,16 @@ impl<Static: StaticAtomSet> Atom<Static> {
         self.clone()
     }
 
+    /// Like [`eq_ignore_ascii_case`].
+    ///
+    /// [`eq_ignore_ascii_case`]: https://doc.rust-lang.org/std/ascii/trait.AsciiExt.html#tymethod.eq_ignore_ascii_case
     pub fn eq_ignore_ascii_case(&self, other: &Self) -> bool {
         (self == other) || self.eq_str_ignore_ascii_case(&**other)
     }
 
+    /// Like [`eq_ignore_ascii_case`], but takes an unhashed string as `other`.
+    ///
+    /// [`eq_ignore_ascii_case`]: https://doc.rust-lang.org/std/ascii/trait.AsciiExt.html#tymethod.eq_ignore_ascii_case
     pub fn eq_str_ignore_ascii_case(&self, other: &str) -> bool {
         (&**self).eq_ignore_ascii_case(other)
     }
@@ -525,6 +556,8 @@ fn inline_atom_slice_mut(x: &mut u64) -> &mut [u8] {
 }
 
 impl UnpackedAtom {
+    /// Pack a key, fitting it into a u64 with flags and data. See `string_cache_shared` for
+    /// hints for the layout.
     #[inline(always)]
     unsafe fn pack(self) -> u64 {
         match self {
@@ -546,6 +579,7 @@ impl UnpackedAtom {
         }
     }
 
+    /// Unpack a key, extracting information from a single u64 into useable structs.
     #[inline(always)]
     unsafe fn from_packed(data: u64) -> UnpackedAtom {
         debug_assert!(DYNAMIC_TAG == 0); // Dynamic is untagged

string-cache-codegen/lib.rs

@@ -82,6 +82,8 @@ use std::path::Path;
 /// A builder for a static atom set and relevant macros
 pub struct AtomType {
     path: String,
+    atom_doc: Option<String>,
+    static_set_doc: Option<String>,
     macro_name: String,
     macro_doc: Option<String>,
     atoms: HashSet<String>,
@@ -108,16 +110,40 @@ impl AtomType {
     /// macro_rules foo_atom {
     ///    // Expands to: $crate::foo::FooAtom { … }
     /// }
+    /// ```
     pub fn new(path: &str, macro_name: &str) -> Self {
-        assert!(macro_name.ends_with("!"));
+        assert!(macro_name.ends_with("!"), "`macro_name` must end with '!'");
         AtomType {
             path: path.to_owned(),
             macro_name: macro_name[..macro_name.len() - "!".len()].to_owned(),
+            atom_doc: None,
+            static_set_doc: None,
             macro_doc: None,
             atoms: HashSet::new(),
         }
     }
 
+    /// Add some documentation to the generated Atom type alias.
+    ///
+    /// This can help the user know that the type uses interned strings.
+    ///
+    /// Note that `docs` should not contain the `///` at the front of normal docs.
+    pub fn with_atom_doc(&mut self, docs: &str) -> &mut Self {
+        self.atom_doc = Some(docs.to_owned());
+        self
+    }
+
+    /// Add some documentation to the generated static set.
+    ///
+    /// This can help the user know that this type is zero-sized and just references a static
+    /// lookup table, or point them to the `Atom` type alias for more info.
+    ///
+    /// Note that `docs` should not contain the `///` at the front of normal docs.
+    pub fn with_static_set_doc(&mut self, docs: &str) -> &mut Self {
+        self.static_set_doc = Some(docs.to_owned());
+        self
+    }
+
     /// Add some documentation to the generated macro.
     ///
     /// Note that `docs` should not contain the `///` at the front of normal docs.
@@ -176,6 +202,14 @@ impl AtomType {
         } else {
             &self.path
         };
+        let atom_doc = match self.atom_doc {
+            Some(ref doc) => quote!(#[doc = #doc]),
+            None => quote!()
+        };
+        let static_set_doc = match self.static_set_doc {
+            Some(ref doc) => quote!(#[doc = #doc]),
+            None => quote!()
+        };
         let macro_doc = match self.macro_doc {
             Some(ref doc) => quote!(#[doc = #doc]),
             None => quote!()
@@ -186,7 +220,9 @@ impl AtomType {
         let path = iter::repeat(quote::Ident::from(&*self.path));
 
         quote! {
+            #atom_doc
             pub type #type_name = ::string_cache::Atom<#static_set_name>;
+            #static_set_doc
             pub struct #static_set_name;
             impl ::string_cache::StaticAtomSet for #static_set_name {
                 fn get() -> &'static ::string_cache::PhfStrSet {