From 68661d5488b194e64f57992cd1b7afe8153a9b95 Mon Sep 17 00:00:00 2001
From: Mark McGranaghan <mmcgrana@gmail.com>
Date: Wed, 10 Oct 2012 09:27:40 -0700
Subject: [PATCH] sha1 hashes

---
 examples.txt                        |  2 +-
 examples/sha1-hashes/sha1-hashes.go | 35 ++++++++++++++++++-----------
 examples/sha1-hashes/sha1-hashes.sh | 14 +++++++++++-
 3 files changed, 36 insertions(+), 15 deletions(-)

diff --git a/examples.txt b/examples.txt
index 88e3aab..441ee3c 100644
--- a/examples.txt
+++ b/examples.txt
@@ -56,7 +56,7 @@ Sorting by Functions
 # Random Numbers
 # Number Parsing
 # URLs
-# SHA1 Hashes
+SHA1 Hashes
 # Base64 Encoding
 # Reading Files
 # Writing Files
diff --git a/examples/sha1-hashes/sha1-hashes.go b/examples/sha1-hashes/sha1-hashes.go
index 951119e..aae181e 100644
--- a/examples/sha1-hashes/sha1-hashes.go
+++ b/examples/sha1-hashes/sha1-hashes.go
@@ -1,28 +1,37 @@
+// SHA1 hashes are frequently used to compute short
+// identities for binary or text blobs. For example, the
+// [git revision control system](http://git-scm.com/) uses
+// SHA1s extensively to identify versioned files and
+// directories. Here's how to compute SHA1 hashes in Go.
+
 package main
 
-// Package `crypto/sha1` computes SHA1 hashes.
+// Go implements several hash functions in various
+// `crtypo/*` packages.
 import "crypto/sha1"
 import "encoding/hex"
 import "fmt"
 
 func main() {
-    // The pattern is `sha1.New()`, `sha1.Write(bytes)`,
-    // then `sha1.Sum([]byte{})
+    s := "sha1 this string"
+
+    // The pattern for generating a hash is `sha1.New()`,
+    // `sha1.Write(bytes)`, then `sha1.Sum([]byte{}).
+    // Here we start with a new hash.
     h := sha1.New()
 
-    // `Write` expects bytes. If you have a string `s`
-    // use `[]byte(s)` to coerce it.
-    h.Write([]byte("sha1 this string"))
+    // `Write` expects bytes. If you have a string `s`,
+    // use `[]byte(s)` to coerce it to bytes.
+    h.Write([]byte(s))
 
-    // Get the result. The argument to `Sum` can be used
-    // to append to an existing buffer: usually uneeded.
+    // This gets the finalized hash result as a byte
+    // slice. The argument to `Sum` can be used to append
+    // to an existing byte slice: it usually isn't needed.
     bs := h.Sum(nil)
 
     // SHA1 values are often printed in hex, for example
-    // with git.
+    // in git commits. Use `hex.EncodeToString` to convert
+    // a hash results to a hex string.
+    fmt.Println(s)
     fmt.Println(hex.EncodeToString(bs))
 }
-
-// You can compute other hashes using a similar
-// pattern. For exmpale, to compute MD5 hashes
-// import `crypto/md5` and use `md5.New()`.
diff --git a/examples/sha1-hashes/sha1-hashes.sh b/examples/sha1-hashes/sha1-hashes.sh
index cd14ec9..4636be3 100644
--- a/examples/sha1-hashes/sha1-hashes.sh
+++ b/examples/sha1-hashes/sha1-hashes.sh
@@ -1,2 +1,14 @@
-$ go run sha1-hashes.go 
+# Running the program computes the hash and prints it in
+# a human-readable hex format.
+$ go run sha1-hashes.go
+sha1 this string
 cf23df2207d99a74fbe169e3eba035e633b65d94
+
+
+# You can compute other hashes using a similar pattern to
+# the one shown above. For exmpale, to compute MD5 hashes
+# import `crypto/md5` and use `md5.New()`.
+
+# Note that if you need cyrtograhpically secure hashes,
+# you should carefully research
+# [hash strength](http://en.wikipedia.org/wiki/Cryptographic_hash_function)!