Add Docs

Author: Kimundi

src/lazy_static.rs

@@ -1,17 +1,73 @@
 /*!
-Macro to declare lazily evaluated statics, which allows runtime initialization.
+A macro for declaring lazily evaluated statics.
 
-The macro works by defining a custom type with a `Deref` impl, which delegates the dereferencing
-to a hidden `static mut` that gets lazily initialized on first access.
+Using this macro, it is possible to have `static`s that require code to be
+executed at runtime in order to be initialized.
+This includes anything requiring heap allocations, like vectors or hash maps,
+as well as anything that requires function calls to be computed.
 
-# Examples
+# Syntax
 
-To load the extension and use it:
+```
+lazy_static! {
+    static ref NAME_1: TYPE_1 = EXPR_1;
+    static ref NAME_2: TYPE_2 = EXPR_2;
+    ...
+    static ref NAME_N: TYPE_N = EXPR_N;
+}
+```
+
+# Semantic
+
+For a given `static ref NAME: TYPE = EXPR;`, the macro generates a
+unique type that implements `Deref<TYPE>` and stores it in a static with name `NAME`.
+
+On first deref, `EXPR` gets evaluated and stored internally, such that all further derefs
+can return a reference to the same object.
+
+Like regular `static mut`s, this macro only works for types that fulfill the `Share`
+trait.
+
+# Example
+
+Using the macro:
 
-```rust,ignore
+```rust
+#![feature(phase)]
 
+#[phase(plugin)]
+extern crate lazy_static;
+
+use std::collections::HashMap;
+
+lazy_static! {
+    static ref HASHMAP: HashMap<uint, &'static str> = {
+        let mut m = HashMap::new();
+        m.insert(0u, "foo");
+        m.insert(1u, "bar");
+        m.insert(2u, "baz");
+        m
+    };
+    static ref COUNT: uint = HASHMAP.len();
+    static ref NUMBER: uint = times_two(21);
+}
+
+fn times_two(n: uint) -> uint { n * 2 }
+
+fn main() {
+    println!("The map has {} entries.", *COUNT);
+    println!("The entry for `0` is \"{}\".", HASHMAP.get(&0));
+    println!("A expensive calculation on a static results in: {}.", *NUMBER);
 }
 ```
+
+# Implementation details
+
+The `Deref` implementation uses a hidden `static mut` that is guarded by a atomic check
+using the `sync::Once` abstraction. All lazily evaluated values are currently
+put in a heap allocated box, due to the Rust language currently not providing any way to
+define uninitialized `static mut` values.
+
 */
 
 #![crate_id = "lazy_static"]