docs: add comments to describe the package

Author: BragdonD

doc.go

@@ -0,0 +1,5 @@
+// Package jsonpointer-go provides functions to use jsonpointer
+// defined by the [RFC 6902] in Golang.
+//
+// [RFC 6902]: https://www.rfc-editor.org/rfc/rfc6902
+package jsonpointergo

pointer.go

@@ -14,12 +14,19 @@ const (
 	JSONPointerTildaEncoded   = "~0"
 )
 
+// JSONObject is a type alias for a map with string keys and values of
+// any type
 type JSONObject = map[string]any
 
+// JSONPointer struct holds the parsed reference tokens of a JSON
+// Pointer
 type JSONPointer struct {
+	// Slice of reference tokens derived from the JSON Pointer
 	referenceTokens []string
 }
 
+// NewJSONPointer creates a new JSONPointer instance from a JSON
+// Pointer string
 func NewJSONPointer(jsonPointer string) (*JSONPointer, error) {
 	tokens, err := parseJSONPointerString(jsonPointer)
 	if err != nil {
@@ -30,6 +37,8 @@ func NewJSONPointer(jsonPointer string) (*JSONPointer, error) {
 	}, nil
 }
 
+// parseJSONPointerString parses a JSON Pointer string into its
+// reference tokens
 func parseJSONPointerString(jsonPointer string) ([]string, error) {
 	if jsonPointer == JSONPointerEmptyPointer {
 		return []string{}, nil
@@ -40,32 +49,39 @@ func parseJSONPointerString(jsonPointer string) ([]string, error) {
 			JSONPointerSeparatorToken,
 		)
 	}
+	// Split the JSON Pointer into tokens
 	tokens := strings.Split(jsonPointer, JSONPointerSeparatorToken)
 	return tokens[1:], nil
 }
 
+// GetValue retrieves the value from the JSON document based on the
+// JSON Pointer
 func (jp *JSONPointer) GetValue(document JSONObject) (any, error) {
 	if document == nil {
 		return nil, fmt.Errorf(
 			"jsonpointer: the JSON document provided is nil",
 		)
 	}
 	var subDocument any
+	// Start with the root of the JSON document
 	subDocument = document
 	for i, tokenRefEncoded := range jp.referenceTokens {
 		tokenRef := decodeJSONPointerReference(tokenRefEncoded)
+		// Handle the case where the value is a JSON object
 		jsonDoc, ok := subDocument.(JSONObject)
 		if ok {
 			value, ok := jsonDoc[tokenRef]
 			if !ok {
 				return nil, fmt.Errorf(
 					"jsonpointer: the document provided does not have the following reference: %v, %v",
-					tokenRef, i,
+					tokenRef,
+					i,
 				)
 			}
 			subDocument = value
 			continue
 		}
+		// Handle the case where the value is an Array
 		jsonArray, ok := subDocument.([]any)
 		if ok {
 			index, err := strconv.Atoi(tokenRef)
@@ -85,19 +101,28 @@ func (jp *JSONPointer) GetValue(document JSONObject) (any, error) {
 			subDocument = jsonArray[index]
 			continue
 		}
-		return nil, fmt.Errorf("jsonpointer: the reference is trying to access a single value: %v. Type of subdocument: %T", tokenRef, subDocument)
+		// Handle the case where the value is a single value
+		return nil, fmt.Errorf(
+			"jsonpointer: the reference is trying to access a single value: %v. Type of subdocument: %T",
+			tokenRef,
+			subDocument,
+		)
 	}
 	return subDocument, nil
 }
 
+// decodeJSONPointerReference decodes a reference token by replacing
+// escape sequences
 func decodeJSONPointerReference(ref string) string {
-	refWithSlash := strings.ReplaceAll(
+	// Replace "~1" with "/"
+	ref = strings.ReplaceAll(
 		ref,
 		JSONPointerSlashEncoded,
 		JSONPointerSeparatorToken,
 	)
+	// Replace "~0" with "~"
 	return strings.ReplaceAll(
-		refWithSlash,
+		ref,
 		JSONPointerTildaEncoded,
 		JSONPointerEscapeToken,
 	)

pointer_test.go

@@ -18,7 +18,12 @@ func TestNewJSONPointer(t *testing.T) {
 	for _, test := range tests {
 		_, err := NewJSONPointer(test.jsonPointer)
 		if (err != nil) != test.wantErr {
-			t.Errorf("NewJSONPointer(%v) error = %v, wantErr %v", test.jsonPointer, err, test.wantErr)
+			t.Errorf(
+				"NewJSONPointer(%v) error = %v, wantErr %v",
+				test.jsonPointer,
+				err,
+				test.wantErr,
+			)
 		}
 	}
 }
@@ -46,15 +51,27 @@ func TestGetValue(t *testing.T) {
 	for _, test := range tests {
 		jp, err := NewJSONPointer(test.jsonPointer)
 		if err != nil {
-			t.Fatalf("NewJSONPointer(%v) error = %v", test.jsonPointer, err)
+			t.Fatalf(
+				"NewJSONPointer(%v) error = %v",
+				test.jsonPointer,
+				err,
+			)
 		}
 		got, err := jp.GetValue(document)
 		if (err != nil) != test.wantErr {
-			t.Errorf("JSONPointer.GetValue() error = %v, wantErr %v", err, test.wantErr)
+			t.Errorf(
+				"JSONPointer.GetValue() error = %v, wantErr %v",
+				err,
+				test.wantErr,
+			)
 			continue
 		}
 		if !reflect.DeepEqual(got, test.want) {
-			t.Errorf("JSONPointer.GetValue() = %v, want %v", got, test.want)
+			t.Errorf(
+				"JSONPointer.GetValue() = %v, want %v",
+				got,
+				test.want,
+			)
 		}
 	}
 }
@@ -71,7 +88,12 @@ func TestDecodeJSONPointerReference(t *testing.T) {
 
 	for _, test := range tests {
 		if got := decodeJSONPointerReference(test.ref); got != test.want {
-			t.Errorf("decodeJSONPointerReference(%v) = %v, want %v", test.ref, got, test.want)
+			t.Errorf(
+				"decodeJSONPointerReference(%v) = %v, want %v",
+				test.ref,
+				got,
+				test.want,
+			)
 		}
 	}
 }