Update package comments to provide better documentation

This updates the package comments in different areas to improve the GoDoc
rendering of the documentation.

Fixes #27

Signed-off-by: Tim Heckman <t@heckman.io>

codec.go

@@ -71,27 +71,38 @@ func (u UUID) MarshalText() ([]byte, error) {
 
 // UnmarshalText implements the encoding.TextUnmarshaler interface.
 // Following formats are supported:
+//
 //   "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
 //   "{6ba7b810-9dad-11d1-80b4-00c04fd430c8}",
 //   "urn:uuid:6ba7b810-9dad-11d1-80b4-00c04fd430c8"
 //   "6ba7b8109dad11d180b400c04fd430c8"
+//   "{6ba7b8109dad11d180b400c04fd430c8}",
+//   "urn:uuid:6ba7b8109dad11d180b400c04fd430c8"
+//
 // ABNF for supported UUID text representation follows:
-//   uuid := canonical | hashlike | braced | urn
-//   plain := canonical | hashlike
-//   canonical := 4hexoct '-' 2hexoct '-' 2hexoct '-' 6hexoct
-//   hashlike := 12hexoct
-//   braced := '{' plain '}'
-//   urn := URN ':' UUID-NID ':' plain
+//
 //   URN := 'urn'
 //   UUID-NID := 'uuid'
-//   12hexoct := 6hexoct 6hexoct
-//   6hexoct := 4hexoct 2hexoct
-//   4hexoct := 2hexoct 2hexoct
-//   2hexoct := hexoct hexoct
-//   hexoct := hexdig hexdig
+//
 //   hexdig := '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' |
 //             'a' | 'b' | 'c' | 'd' | 'e' | 'f' |
 //             'A' | 'B' | 'C' | 'D' | 'E' | 'F'
+//
+//   hexoct := hexdig hexdig
+//   2hexoct := hexoct hexoct
+//   4hexoct := 2hexoct 2hexoct
+//   6hexoct := 4hexoct 2hexoct
+//   12hexoct := 6hexoct 6hexoct
+//
+//   hashlike := 12hexoct
+//   canonical := 4hexoct '-' 2hexoct '-' 2hexoct '-' 6hexoct
+//
+//   plain := canonical | hashlike
+//   uuid := canonical | hashlike | braced | urn
+//
+//   braced := '{' plain '}' | '{' hashlike  '}'
+//   urn := URN ':' UUID-NID ':' plain
+//
 func (u *UUID) UnmarshalText(text []byte) error {
 	switch len(text) {
 	case 32:

generator.go

@@ -42,10 +42,10 @@ const epochStart = 122192928000000000
 type epochFunc func() time.Time
 type hwAddrFunc func() (net.HardwareAddr, error)
 
-var (
-	// DefaultGenerator is the default Generator used.
-	DefaultGenerator = newRFC4122Generator()
+// DefaultGenerator is the default Generator used.
+var DefaultGenerator = newRFC4122Generator()
 
+var (
 	posixUID = uint32(os.Getuid())
 	posixGID = uint32(os.Getgid())
 )

uuid.go

@@ -37,7 +37,7 @@ import (
 // Size of a UUID in bytes.
 const Size = 16
 
-// UUID representation compliant with specification described in RFC-4122.
+// UUID is an array type to represent the value of a UUID, as defined in RFC-4122.
 type UUID [Size]byte
 
 // UUID versions.
@@ -71,7 +71,8 @@ var (
 	byteGroups = []int{8, 4, 4, 4, 12}
 )
 
-// Nil is nil UUID, as specified in RFC-4122, that has all 128 bits set to zero.
+// Nil is the nil UUID, as specified in RFC-4122, that has all 128 bits set to
+// zero.
 var Nil = UUID{}
 
 // Predefined namespace UUIDs.