Refine doc comments

README.md

@@ -17,12 +17,12 @@ MSRV (minimum supported rust version) is Rust 1.46.
 
 ## Usage
 
-PHF data structures can be constucted via either the procedural 
-macros in the `phf_macros` crate or code generation supported by the 
+PHF data structures can be constructed via either the procedural
+macros in the `phf_macros` crate or code generation supported by the
 `phf_codegen` crate.
 
 To compile the `phf` crate with a dependency on
-libcore instead of libstd, enabling use in environments where libstd 
+libcore instead of libstd, enabling use in environments where libstd
 will not work, set `default-features = false` for the dependency:
 
 ```toml

phf/src/lib.rs

@@ -1,50 +1,76 @@
-//! Compile-time generated maps and sets.
+//! Rust-PHF is a library to generate efficient lookup tables at compile time using
+//! [perfect hash functions](http://en.wikipedia.org/wiki/Perfect_hash_function).
 //!
-//! The `phf::Map` and `phf::Set` types have roughly comparable performance to
-//! a standard hash table, but can be generated as compile-time static values.
+//! It currently uses the
+//! [CHD algorithm](http://cmph.sourceforge.net/papers/esa09.pdf) and can generate
+//! a 100,000 entry map in roughly .4 seconds. By default statistics are not
+//! produced, but if you set the environment variable `PHF_STATS` it will issue
+//! a compiler note about how long it took.
 //!
-//! # Usage
+//! MSRV (minimum supported rust version) is Rust 1.46.
 //!
-//! If the `macros` Cargo feature is enabled, the `phf_map`, `phf_set`,
-//! `phf_ordered_map`, and `phf_ordered_set` macros can be used to construct
-//! the PHF type. This method can be used with a stable compiler
-//! (minimum supported rust version is 1.46.
-//! feature).
+//! ## Usage
 //!
-//! ```toml
+//! PHF data structures can be constructed via either the procedural
+//! macros in the `phf_macros` crate or code generation supported by the
+//! `phf_codegen` crate. If you prefer macros, you can easily use them by
+//! enabling the `macros` feature of the `phf` crate, like:
+//!
+//!```toml
 //! [dependencies]
 //! phf = { version = "0.10", features = ["macros"] }
 //! ```
 //!
+//! To compile the `phf` crate with a dependency on
+//! libcore instead of libstd, enabling use in environments where libstd
+//! will not work, set `default-features = false` for the dependency:
+//!
+//! ```toml
+//! [dependencies]
+//! # to use `phf` in `no_std` environments
+//! phf = { version = "0.10", default-features = false }
 //! ```
-//! use phf::{phf_map, phf_set};
 //!
-//! static MY_MAP: phf::Map<&'static str, u32> = phf_map! {
-//!     "hello" => 1,
-//!     "world" => 2,
-//! };
+//! ## Example (with the `macros` feature enabled)
 //!
-//! static MY_SET: phf::Set<&'static str> = phf_set! {
-//!     "hello world",
-//!     "hola mundo",
+//! ```rust
+//! use phf::phf_map;
+//!
+//! #[derive(Clone)]
+//! pub enum Keyword {
+//!     Loop,
+//!     Continue,
+//!     Break,
+//!     Fn,
+//!     Extern,
+//! }
+//!
+//! static KEYWORDS: phf::Map<&'static str, Keyword> = phf_map! {
+//!     "loop" => Keyword::Loop,
+//!     "continue" => Keyword::Continue,
+//!     "break" => Keyword::Break,
+//!     "fn" => Keyword::Fn,
+//!     "extern" => Keyword::Extern,
 //! };
 //!
-//! fn main() {
-//!     assert_eq!(MY_MAP["hello"], 1);
-//!     assert!(MY_SET.contains("hello world"));
+//! pub fn parse_keyword(keyword: &str) -> Option<Keyword> {
+//!     KEYWORDS.get(keyword).cloned()
 //! }
 //! ```
 //!
-//! Alternatively, you can use the `phf_codegen` crate to generate PHF datatypes
+//! Alternatively, you can use the [`phf_codegen`] crate to generate PHF datatypes
 //! in a build script.
 //!
+//! [`phf_codegen`]: https://docs.rs/phf_codegen
+//!
 //! ## Note
 //!
 //! Currently, the macro syntax has some limitations and may not
 //! work as you want. See [#183] or [#196] for example.
 //!
 //! [#183]: https://github.com/rust-phf/rust-phf/issues/183
 //! [#196]: https://github.com/rust-phf/rust-phf/issues/196
+
 #![doc(html_root_url = "https://docs.rs/phf/0.10")]
 #![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]

phf_codegen/src/lib.rs

@@ -5,7 +5,11 @@
 //! generate a Rust source file that will be included in a library at build
 //! time.
 //!
-//! # Examples
+//! For more information about `rust-phf` crates, see [the `phf` crate's documentation][phf].
+//!
+//! [phf]: https://docs.rs/phf
+//!
+//! ## Examples
 //!
 //! build.rs:
 //!
@@ -52,7 +56,7 @@
 //! }
 //! ```
 //!
-//! ##### Byte-String Keys
+//! ### Byte-String Keys
 //! Byte strings by default produce references to fixed-size arrays; the compiler needs a hint
 //! to coerce them to slices:
 //!
@@ -101,7 +105,7 @@
 //! }
 //! ```
 //!
-//! # Note
+//! ## Note
 //!
 //! The compiler's stack will overflow when processing extremely long method
 //! chains (500+ calls). When generating large PHF data structures, consider
@@ -123,6 +127,7 @@
 //! builder.entry("world", "2");
 //! // ...
 //! ```
+
 #![doc(html_root_url = "https://docs.rs/phf_codegen/0.10")]
 
 use phf_shared::{FmtConst, PhfHash};

phf_generator/src/lib.rs

@@ -1,3 +1,7 @@
+//! See [the `phf` crate's documentation][phf] for details.
+//!
+//! [phf]: https://docs.rs/phf
+
 #![doc(html_root_url = "https://docs.rs/phf_generator/0.10")]
 use phf_shared::{HashKey, PhfHash};
 use rand::distributions::Standard;

phf_macros/src/lib.rs

@@ -1,3 +1,8 @@
+//! A set of macros to generate Rust source for PHF data structures at compile time.
+//! See [the `phf` crate's documentation][phf] for details.
+//!
+//! [phf]: https://docs.rs/phf
+
 // FIXME: Remove `extern crate` below when we bump MSRV to 1.42 or higher.
 extern crate proc_macro;
 

phf_shared/src/lib.rs

@@ -1,3 +1,7 @@
+//! See [the `phf` crate's documentation][phf] for details.
+//!
+//! [phf]: https://docs.rs/phf
+
 #![doc(html_root_url = "https://docs.rs/phf_shared/0.10")]
 #![cfg_attr(not(feature = "std"), no_std)]