some literate experiments

README

@@ -15,8 +15,12 @@ get web presence in good enough shape to point to from blog post
     subscription management
 
 validate book style in editor
+  22-varags
+  xx-rand
+  xx-sha1
 
 validate book style in web mockup
+  http://jashkenas.github.com/docco/
 
 join Google+ and claim website
 

src/xx-dns.go

@@ -4,4 +4,4 @@ import ("net/dns", "fmt")
 
 func main() {
 	// https://github.com/miekg/dns/blob/master/ex/q/q.go
-}
+}

src/xx-rand.go

@@ -1,15 +1,26 @@
+                                                    // The `math/rand` package provides psuedo-random numbers.
+
 package main
 
-import ("math/rand"; "fmt")
+import (
+	"math/rand"
+	"fmt"
+)
 
 func main() {
-	fmt.Println(rand.Intn(100))
-	fmt.Println(rand.Intn(100))
+	fmt.Println(rand.Intn(100))                     // For example, `rand.Intn` returns a random `int` n,
+	fmt.Println(rand.Intn(100))                     // `0 <= n < 100`.
 
-	r1 := rand.New(rand.NewSource(int64(1337)))
-	fmt.Println(r1.Intn(100))
-	fmt.Println(r1.Intn(100))
-	r2 := rand.New(rand.NewSource(int64(1337)))
-	fmt.Println(r2.Intn(100))
+
+	fmt.Println(rand.Float64())                     // `rand.Float64` returns a `float64` `f`, `0.0 <= f < 1.0`.
+
+	r1 := rand.New(rand.NewSource(int64(1337)))     // To make the psuedo-random generator deterministic, give it a
+												    // well-known seed.
+	
+	fmt.Println(r1.Intn(100))                       // Call the resulting `rand.Source` just like the functions on
+	fmt.Println(r1.Intn(100))                       // the `rand` package.
+
+	r2 := rand.New(rand.NewSource(int64(1337)))     // If you seed a source with the same number, it produces the
+	fmt.Println(r2.Intn(100))                       // same sequence of random numbers.
 	fmt.Println(r2.Intn(100))
 }

src/xx-sha1.go

@@ -1,10 +1,25 @@
+	                                        // `crypto/sha1` computes SHA1 hashes.
+
 package main
 
-import ("fmt"; "crypto/sha1"; "encoding/hex")
+import (
+	"fmt"
+	"crypto/sha1"
+	"encoding/hex"
+)
 
 func main() {
-    h := sha1.New()
-    h.Write([]byte("sha1 this string"))
-    bs := h.Sum([]byte{})
-	fmt.Println(hex.EncodeToString(bs))
+    h := sha1.New()                         // The basic pattern is `sha1.New()`, `sha1.Write(bytes)`, then
+                                            // `sha1.Sum([]byte{})
+
+    h.Write([]byte("sha1 this string"))     // `Write` expects bytes. If you have a string `s` use
+											// `[]byte(s)` to coerce it.
+
+    bs := h.Sum(nil)                        // Get the result. The argument to `Sum` can be used to append
+                                            // to an existing buffer, but usually you won't need it.
+
+	fmt.Println(hex.EncodeToString(bs))     // SHA1 values are often printed in hex, for example with git.
 }
+
+                                            // You can compute other hashes like MD5 using the same
+                                            // pattern. Import `crypto/md5` and use `md5.New()`.