Update README

Author: Kimundi

README.md

@@ -1,4 +1,64 @@
 lazy-static.rs
 ==============
 
-A small Rust syntax extension for defining lazy evaluated static variables.
+A macro for declaring lazily evaluated statics in Rust.
+
+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.
+
+# Syntax
+
+```
+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
+#![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);
+}
+```