From 75c56b1589b7382a2591fdb9ee3cee88b320ef4a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20BIDON?= <fredbi@yahoo.com>
Date: Fri, 14 Nov 2025 00:06:31 +0100
Subject: [PATCH] doc: added examples to document simple use cases
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Also: fix(ci): scheduled vuln scan once a week is enough, no need to run
it every day

Signed-off-by: Frédéric BIDON <fredbi@yahoo.com>
---
 .github/workflows/scanner.yml |  2 +-
 README.md                     | 38 ++++++++++++++++++--
 examples_test.go              | 65 +++++++++++++++++++++++++++++++++++
 pointer.go                    |  5 +--
 4 files changed, 105 insertions(+), 5 deletions(-)
 create mode 100644 examples_test.go

diff --git a/.github/workflows/scanner.yml b/.github/workflows/scanner.yml
index bd18926..285c225 100644
--- a/.github/workflows/scanner.yml
+++ b/.github/workflows/scanner.yml
@@ -15,7 +15,7 @@ on:
   push:
     branches: [ "master" ]
   schedule:
-    - cron: '18 4 * * *'
+    - cron: '18 4 * * 3'
 
 jobs:
   analysis:
diff --git a/README.md b/README.md
index 1b894ce..24889f4 100644
--- a/README.md
+++ b/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 -->
diff --git a/examples_test.go b/examples_test.go
new file mode 100644
index 0000000..8a8dc1a
--- /dev/null
+++ b/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"}}
+}
diff --git a/pointer.go b/pointer.go
index 41d8eca..35c8eff 100644
--- a/pointer.go
+++ b/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
 }