From 1fd6936a12354b8194b959e560f584d60b40be80 Mon Sep 17 00:00:00 2001 From: Trevor Starick Date: Fri, 13 Jul 2018 23:56:38 -0400 Subject: [PATCH] documentation: amends review requested for pull request #12 --- codec.go | 14 +++++++------- generator.go | 2 +- uuid.go | 15 +++++++++------ 3 files changed, 17 insertions(+), 14 deletions(-) diff --git a/codec.go b/codec.go index c75c5ff..7957673 100644 --- a/codec.go +++ b/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) { diff --git a/generator.go b/generator.go index c48712b..467c167 100644 --- a/generator.go +++ b/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 { diff --git a/uuid.go b/uuid.go index a3d19b0..960c638 100644 --- a/uuid.go +++ b/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)