documentation: amends review requested for pull request gofrs#12

codec.go

@@ -35,7 +35,7 @@ func FromBytes(input []byte) (u UUID, err error) {
 }
 
 // FromBytesOrNil returns a UUID generated from the raw byte slice input.
-// Same behavior as FromBytes(), but returns a Nil UUID instead of an error.
+// Same behavior as FromBytes(), but returns uuid.Nil instead of an error.
 func FromBytesOrNil(input []byte) UUID {
  uuid, err := FromBytes(input)
  if err != nil {
@@ -52,7 +52,7 @@ func FromString(input string) (u UUID, err error) {
 }
 
 // FromStringOrNil returns a UUID parsed from the input string.
-// Same behavior as FromString(), but returns a Nil UUID instead of an error.
+// Same behavior as FromString(), but returns uuid.Nil instead of an error.
 func FromStringOrNil(input string) UUID {
  uuid, err := FromString(input)
  if err != nil {
@@ -108,7 +108,7 @@ func (u *UUID) UnmarshalText(text []byte) (err error) {
  }
 }
 
-// decodeCanonical decodes UUID strings that are formatted like the following format:
+// decodeCanonical decodes UUID strings that are formatted as defined in RFC-4122 (section 3):
 // "6ba7b810-9dad-11d1-80b4-00c04fd430c8".
 func (u *UUID) decodeCanonical(t []byte) (err error) {
  if t[8] != '-' || t[13] != '-' || t[18] != '-' || t[23] != '-' {
@@ -133,7 +133,7 @@ func (u *UUID) decodeCanonical(t []byte) (err error) {
  return
 }
 
-// decodeHashLike decodes UUID strings that are formatted like the following format:
+// decodeHashLike decodes UUID strings that are using the following format:
 // "6ba7b8109dad11d180b400c04fd430c8".
 func (u *UUID) decodeHashLike(t []byte) (err error) {
  src := t[:]
@@ -145,7 +145,7 @@ func (u *UUID) decodeHashLike(t []byte) (err error) {
  return
 }
 
-// decodeBraced decodes UUID strings that are formatted like the following formats:
+// decodeBraced decodes UUID strings that are using the following formats:
 // "{6ba7b810-9dad-11d1-80b4-00c04fd430c8}"
 // "{6ba7b8109dad11d180b400c04fd430c8}".
 func (u *UUID) decodeBraced(t []byte) (err error) {
@@ -158,7 +158,7 @@ func (u *UUID) decodeBraced(t []byte) (err error) {
  return u.decodePlain(t[1 : l-1])
 }
 
-// decodeURN decodes UUID strings that are formatted like the following formats:
+// decodeURN decodes UUID strings that are using the following formats:
 // "urn:uuid:6ba7b810-9dad-11d1-80b4-00c04fd430c8"
 // "urn:uuid:6ba7b8109dad11d180b400c04fd430c8".
 func (u *UUID) decodeURN(t []byte) (err error) {
@@ -173,7 +173,7 @@ func (u *UUID) decodeURN(t []byte) (err error) {
  return u.decodePlain(t[9:total])
 }
 
-// decodePlain decodes UUID strings that are formatted like the following formats:
+// decodePlain decodes UUID strings that are using the following formats:
 // "6ba7b810-9dad-11d1-80b4-00c04fd430c8" or in hash-like format
 // "6ba7b8109dad11d180b400c04fd430c8".
 func (u *UUID) decodePlain(t []byte) (err error) {

generator.go

@@ -225,7 +225,7 @@ func (g *rfc4122Generator) getHardwareAddr() ([]byte, error) {
  if _, err = io.ReadFull(g.rand, g.hardwareAddr[:]); err != nil {
  return
  }
- // Set multicast bit as recommended by RFC 4122
+ // Set multicast bit as recommended by RFC-4122
  g.hardwareAddr[0] |= 0x01
  })
  if err != nil {

uuid.go

@@ -19,11 +19,14 @@
 // OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-// Package uuid provides implementations of the Universally Unique Identifier (UUID), as specified in RFC 4122 and DCE 1.1.
+// Package uuid provides implementations of the Universally Unique Identifier (UUID), as specified in RFC-4122 and DCE 1.1.
 //
-// RFC 4122 (https://tools.ietf.org/html/rfc4122) provides the specification for versions 1, 3, 4, and 5.
+// RFC-4122[1] provides the specification for versions 1, 3, 4, and 5.
 //
-// DCE 1.1 (http://pubs.opengroup.org/onlinepubs/9696989899/chap5.htm#tagcjh_08_02_01_01) provides the specification for version 2.
+// DCE 1.1[2] provides the specification for version 2.
+//
+// [1] https://tools.ietf.org/html/rfc4122
+// [2] http://pubs.opengroup.org/onlinepubs/9696989899/chap5.htm#tagcjh_08_02_01_01
 package uuid
 
 import (
@@ -34,7 +37,7 @@ import (
 // Size of a UUID in bytes.
 const Size = 16
 
-// UUID representation compliant with specification described in RFC 4122.
+// UUID representation compliant with specification described in RFC-4122.
 type UUID [Size]byte
 
 // UUID versions.
@@ -68,7 +71,7 @@ var (
  byteGroups = []int{8, 4, 4, 4, 12}
 )
 
-// Nil is special form of UUID that is specified to have all 128 bits set to zero.
+// Nil is nil UUID, as specified in RFC-4122, that has all 128 bits set to zero.
 var Nil = UUID{}
 
 // Predefined namespace UUIDs.
@@ -110,7 +113,7 @@ func (u UUID) Bytes() []byte {
  return u[:]
 }
 
-// String returns a canonical string representation of the UUID:
+// String returns a canonical RFC-4122 string representation of the UUID:
 // xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
 func (u UUID) String() string {
  buf := make([]byte, 36)