Add documentation for phf_macros

phf/src/lib.rs

@@ -1,38 +1,8 @@
 //! Compile time optimized maps and sets.
 //!
-//! Keys can be string literals, byte string literals, byte literals, char
-//! literals, or any of the fixed-size isizeegral types.
-//!
-//! # Examples
-//!
-//! ```rust
-//! #![feature(plugin)]
-//! #![plugin(phf_macros)]
-//!
-//! extern crate phf;
-//!
-//! #[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,
-//! };
-//!
-//! pub fn parse_keyword(keyword: &str) -> Option<Keyword> {
-//!     KEYWORDS.get(keyword).cloned()
-//! }
-//! # fn main() {}
-//! ```
+//! PHF data structures can be generated via the syntax extensions in the
+//! `phf_macros` crate or via code generation in the `phf_codegen` crate. See
+//! the documentation of those crates for more details.
 #![doc(html_root_url="https://sfackler.github.io/rust-phf/doc")]
 #![feature(core, no_std)]
 #![warn(missing_docs)]

phf/src/map.rs

@@ -10,27 +10,11 @@ use phf_shared;
 
 /// An immutable map constructed at compile time.
 ///
-/// `Map`s may be created with the `phf_map` macro:
-///
-/// ```rust
-/// #![feature(plugin)]
-/// #![plugin(phf_macros)]
-///
-/// extern crate phf;
-///
-/// static MY_MAP: phf::Map<&'static str, isize> = phf_map! {
-///    "hello" => 10,
-///    "world" => 11,
-/// };
-///
-/// # fn main() {}
-/// ```
-///
 /// ## Note
 ///
 /// The fields of this struct are public so that they may be initialized by the
-/// `phf_map` macro. They are subject to change at any time and should never
-/// be accessed directly.
+/// `phf_map!` macro and code generation. They are subject to change at any
+/// time and should never be accessed directly.
 pub struct Map<K:'static, V:'static> {
     #[doc(hidden)]
     pub key: u64,

phf/src/ordered_map.rs

@@ -14,27 +14,11 @@ use phf_shared;
 /// Unlike a `Map`, iteration order is guaranteed to match the definition
 /// order.
 ///
-/// `OrderedMap`s may be created with the `phf_ordered_map` macro:
-///
-/// ```rust
-/// #![feature(plugin)]
-/// #![plugin(phf_macros)]
-///
-/// extern crate phf;
-///
-/// static MY_MAP: phf::OrderedMap<&'static str, isize> = phf_ordered_map! {
-///    "hello" => 10,
-///    "world" => 11,
-/// };
-///
-/// # fn main() {}
-/// ```
-///
 /// ## Note
 ///
 /// The fields of this struct are public so that they may be initialized by the
-/// `phf_ordered_map` macro. They are subject to change at any time and should
-/// never be accessed directly.
+/// `phf_ordered_map!` macro and code generation. They are subject to change at
+/// any time and should never be accessed directly.
 pub struct OrderedMap<K:'static, V:'static> {
     #[doc(hidden)]
     pub key: u64,

phf/src/ordered_set.rs

@@ -11,27 +11,11 @@ use {PhfHash, OrderedMap};
 /// Unlike a `Set`, iteration order is guaranteed to match the definition
 /// order.
 ///
-/// `OrderedSet`s may be created with the `phf_ordered_set` macro:
-///
-/// ```rust
-/// #![feature(plugin)]
-/// #![plugin(phf_macros)]
-///
-/// extern crate phf;
-///
-/// static MY_SET: phf::OrderedSet<&'static str> = phf_ordered_set! {
-///    "hello",
-///    "world",
-/// };
-///
-/// # fn main() {}
-/// ```
-///
 /// ## Note
 ///
 /// The fields of this struct are public so that they may be initialized by the
-/// `phf_ordered_set` macro. They are subject to change at any time and should
-/// never be accessed directly.
+/// `phf_ordered_set!` macro and code generation. They are subject to change at
+/// any time and should never be accessed directly.
 pub struct OrderedSet<T:'static> {
     #[doc(hidden)]
     pub map: OrderedMap<T, ()>,

phf/src/set.rs

@@ -10,27 +10,11 @@ use Map;
 
 /// An immutable set constructed at compile time.
 ///
-/// `Set`s may be created with the `phf_set` macro:
-///
-/// ```rust
-/// #![feature(plugin)]
-/// #![plugin(phf_macros)]
-///
-/// extern crate phf;
-///
-/// static MY_SET: phf::Set<&'static str> = phf_set! {
-///    "hello",
-///    "world",
-/// };
-///
-/// # fn main() {}
-/// ```
-///
 /// ## Note
 ///
 /// The fields of this struct are public so that they may be initialized by the
-/// `phf_set` macro. They are subject to change at any time and should never be
-/// accessed directly.
+/// `phf_set!` macro and code generation. They are subject to change at any
+/// time and should never be accessed directly.
 pub struct Set<T:'static> {
     #[doc(hidden)]
     pub map: Map<T, ()>

phf_macros/src/lib.rs

@@ -1,6 +1,35 @@
-//! Compiler plugin for Rust-PHF
+//! Compiler plugin defining macros that create PHF data structures.
 //!
-//! See the documentation for the `phf` crate for more details.
+//! # Example
+//!
+//! ```rust
+//! #![feature(plugin)]
+//! #![plugin(phf_macros)]
+//!
+//! extern crate phf;
+//!
+//! #[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,
+//! };
+//!
+//! pub fn parse_keyword(keyword: &str) -> Option<Keyword> {
+//!     KEYWORDS.get(keyword).cloned()
+//! }
+//! # fn main() {}
+//! ```
 #![doc(html_root_url="http://sfackler.github.io/rust-phf/doc")]
 #![feature(plugin_registrar, quote, rustc_private, env, std_misc)]
 
@@ -30,6 +59,7 @@ use util::{Entry, Key};
 use util::{create_map, create_set, create_ordered_map, create_ordered_set};
 
 pub mod util;
+mod macros;
 
 #[plugin_registrar]
 #[doc(hidden)]

phf_macros/src/macros.rs

@@ -0,0 +1,87 @@
+/// Constructs a `phf::Map` at compile time.
+///
+/// # Examples
+///
+/// ```rust
+/// #![feature(plugin)]
+/// #![plugin(phf_macros)]
+///
+/// extern crate phf;
+///
+/// static MY_MAP: phf::Map<&'static str, i32> = phf_map! {
+///    "hello" => 10,
+///    "world" => 11,
+/// };
+///
+/// # fn main() {}
+/// ```
+#[macro_export]
+macro_rules! phf_map {
+    ($($key:expr => $value:expr),*) => {/* ... */}
+}
+
+/// Constructs a `phf::Set` at compile time.
+///
+/// # Examples
+///
+/// ```rust
+/// #![feature(plugin)]
+/// #![plugin(phf_macros)]
+///
+/// extern crate phf;
+///
+/// static MY_SET: phf::Set<&'static str> = phf_set! {
+///    "hello",
+///    "world",
+/// };
+///
+/// # fn main() {}
+/// ```
+#[macro_export]
+macro_rules! phf_set {
+    ($($entry:expr),*) => {/* ... */}
+}
+
+/// Constructs a `phf::OrderedMap` at compile time.
+///
+/// # Examples
+///
+/// ```rust
+/// #![feature(plugin)]
+/// #![plugin(phf_macros)]
+///
+/// extern crate phf;
+///
+/// static MY_MAP: phf::OrderedMap<&'static str, i32> = phf_ordered_map! {
+///    "hello" => 10,
+///    "world" => 11,
+/// };
+///
+/// # fn main() {}
+/// ```
+#[macro_export]
+macro_rules! phf_ordered_map {
+    ($($key:expr => $value:expr),*) => {/* ... */}
+}
+
+/// Constructs a `phf::OrderedSet` at compile time.
+///
+/// # Examples
+///
+/// ```rust
+/// #![feature(plugin)]
+/// #![plugin(phf_macros)]
+///
+/// extern crate phf;
+///
+/// static MY_SET: phf::OrderedSet<&'static str> = phf_ordered_set! {
+///    "hello",
+///    "world",
+/// };
+///
+/// # fn main() {}
+/// ```
+#[macro_export]
+macro_rules! phf_ordered_set {
+    ($($entry:expr),*) => {/* ... */}
+}