doc: added examples to document simple use cases

.github/workflows/scanner.yml

@@ -15,7 +15,7 @@ on:
   push:
     branches: [ "master" ]
   schedule:
-    - cron: '18 4 * * *'
+    - cron: '18 4 * * 3'
 
 jobs:
   analysis:

README.md

@@ -20,6 +20,40 @@ An implementation of JSON Pointer for golang, which supports go `struct`.
 
 API is stable.
 
+## Import this library in your project
+
+```cmd
+go get github.com/go-openapi/jsonpointer
+```
+
+## Basic usage
+
+See [examples](./examples_test.go)
+
+```go
+  import (
+    "github.com/go-openapi/jsonpointer"
+  )
+
+  ...
+
+	pointer, err := jsonpointer.New("/foo/1")
+	if err != nil {
+		... // error: e.g. invalid JSON pointer specification
+	}
+
+	value, kind, err := pointer.Get(doc)
+	if err != nil {
+		... // error: e.g. key not found, index out of bounds, etc.
+	}
+
+  ...
+```
+
+## Change log
+
+See <https://github.com/go-openapi/jsonpointer/releases>
+
 ## References
 
 <https://tools.ietf.org/html/draft-ietf-appsawg-json-pointer-07>
@@ -62,8 +96,8 @@ using the special trailing character "-" is not implemented.
 <!-- Badges: documentation & support -->
 [doc-badge]: https://img.shields.io/badge/doc-site-blue?link=https%3A%2F%2Fgoswagger.io%2Fgo-openapi%2F
 [doc-url]: https://goswagger.io/go-openapi
-[godoc-badge]: https://godoc.org/github.com/go-openapi/jsonpointer?status.svg
-[godoc-url]: http://godoc.org/github.com/go-openapi/jsonpointer
+[godoc-badge]: https://pkg.go.dev/github.com/go-openapi/jsonpointer?status.svg
+[godoc-url]: http://pkg.go.dev/github.com/go-openapi/jsonpointer
 [slack-badge]: https://slackin.goswagger.io/badge.svg
 [slack-url]: https://slackin.goswagger.io
 <!-- Badges: license & compliance -->

examples_test.go

@@ -0,0 +1,65 @@
+// SPDX-FileCopyrightText: Copyright (c) 2015-2025 go-swagger maintainers
+// SPDX-License-Identifier: Apache-2.0
+
+package jsonpointer
+
+import (
+	"encoding/json"
+	"fmt"
+)
+
+type exampleDocument struct {
+	Foo []string `json:"foo"`
+}
+
+func ExamplePointer_Get() {
+	var doc exampleDocument
+
+	if err := json.Unmarshal(testDocumentJSONBytes, &doc); err != nil { // populates doc
+		panic(err)
+	}
+
+	pointer, err := New("/foo/1")
+	if err != nil {
+		panic(err)
+	}
+
+	value, kind, err := pointer.Get(doc)
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Printf(
+		"value: %q\nkind: %v\n",
+		value, kind,
+	)
+
+	// Output:
+	// value: "baz"
+	// kind: string
+}
+
+func ExamplePointer_Set() {
+	var doc exampleDocument
+
+	if err := json.Unmarshal(testDocumentJSONBytes, &doc); err != nil { // populates doc
+		panic(err)
+	}
+
+	pointer, err := New("/foo/1")
+	if err != nil {
+		panic(err)
+	}
+
+	result, err := pointer.Set(&doc, "hey my")
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Printf("result: %#v\n", result)
+	fmt.Printf("doc: %#v\n", doc)
+
+	// Output:
+	// result: &jsonpointer.exampleDocument{Foo:[]string{"bar", "hey my"}}
+	// doc: jsonpointer.exampleDocument{Foo:[]string{"bar", "hey my"}}
+}

pointer.go

@@ -64,8 +64,9 @@ func (p *Pointer) DecodedTokens() []string {
 	return result
 }
 
-// IsEmpty returns true if this is an empty json pointer
-// this indicates that it points to the root document
+// IsEmpty returns true if this is an empty json pointer.
+//
+// This indicates that it points to the root document.
 func (p *Pointer) IsEmpty() bool {
 	return len(p.referenceTokens) == 0
 }