Fix doc links & typos, move WithRegistry example

Author: theory

CHANGELOG.md

@@ -13,15 +13,23 @@ All notable changes to this project will be documented in this file. It uses the
 
 *   Made significant changes to the `spec` package toward public stability,
     usability, and greater comprehension. The names of things are more
-    consistent, the APIs more legible and user-friendly, and the documentation
-    thorough, with examples for each significant type. See [PR #14] for
+    consistent, the APIs more legible and user-friendly. See [PR #14] for
     details.
-*   Removed the "Package Stability" statement from the README, as all packages
-    are considered stable.
 *   Added support for [json.Number] values to complement the existing support
     for Go core numeric types. This should allow for transparent handling of
     values marshaled with [json.Decoder.UseNumber] enabled.
 
+### 📚 Documentation
+
+*   Vastly expanded the `spec` package documentation to make it much more
+    thorough and accurate, with copious links to relevant parts of [RFC 9535]
+    and complete lists of interface implementations and examples for each
+    significant type. See [PR #14] for details.
+*   Removed the "Package Stability" statement from the README, as all packages
+    are considered stable.
+*   Fixed links and typos in the main package documentation, and moved the
+    registry example under `WithRegistry`.
+
 ### 📔 Notes
 
 *   Upgraded the [compliance test suite] and integrated its located path test
@@ -32,6 +40,8 @@ All notable changes to this project will be documented in this file. It uses the
   [json.Decoder.UseNumber]: https://pkg.go.dev/encoding/json#Decoder.UseNumber
   [PR #14]: https://github.com/theory/jsonpath/pull/14
   [compliance test suite]: https://github.com/jsonpath-standard/jsonpath-compliance-test-suite
+  [RFC 9535]: https://www.rfc-editor.org/rfc/rfc9535.html
+    "RFC 9535 JSONPath: Query Expressions for JSON"
 
 ## [v0.4.1] — 2025-05-02
 

parser/parse.go

@@ -35,8 +35,8 @@ type parser struct {
 	reg *registry.Registry
 }
 
-// Parse parses path, a JSON Path query string, into a PathQuery. Returns a
-// PathParseError on parse failure.
+// Parse parses path, a JSONPath query string, into a [spec.PathQuery].
+// Returns a [ErrPathParse] on parse failure.
 func Parse(reg *registry.Registry, path string) (*spec.PathQuery, error) {
 	lex := newLexer(path)
 	tok := lex.scan()

path.go

@@ -20,18 +20,18 @@ type Path struct {
 	q *spec.PathQuery
 }
 
-// New creates and returns a new Path consisting of q.
+// New creates and returns a new [Path] consisting of q.
 func New(q *spec.PathQuery) *Path {
 	return &Path{q: q}
 }
 
-// Parse parses path, a JSONPath query string, into a Path. Returns an
-// ErrPathParse on parse failure.
+// Parse parses path, a JSONPath query string, into a [Path]. Returns an
+// [ErrPathParse] on parse failure.
 func Parse(path string) (*Path, error) {
 	return NewParser().Parse(path)
 }
 
-// MustParse parses path into a Path. Panics with an ErrPathParse on parse
+// MustParse parses path into a [Path]. Panics with an [ErrPathParse] on parse
 // failure.
 func MustParse(path string) *Path {
 	return NewParser().MustParse(path)
@@ -42,20 +42,21 @@ func (p *Path) String() string {
 	return p.q.String()
 }
 
-// Query returns p's root Query.
+// Query returns p's root [spec.PathQuery].
 func (p *Path) Query() *spec.PathQuery {
 	return p.q
 }
 
-// Select returns the values that JSONPath query p selects from input.
+// Select returns the nodes that JSONPath query p selects from input.
 func (p *Path) Select(input any) NodeList {
 	return p.q.Select(nil, input)
 }
 
-// SelectLocated returns the values that JSONPath query p selects from input
-// as [spec.LocatedNode] values that pair the values with the [normalized
-// paths] that identify them. Unless you have a specific need for the unique
-// normalized path for each value, you probably want to use [Path.Select].
+// SelectLocated returns the nodes that JSONPath query p selects from input as
+// [spec.LocatedNode] values that pair the nodes with the [normalized paths]
+// that identify them. Unless you have a specific need for the unique
+// [spec.NormalizedPath] for each value, you probably want to use
+// [Path.Select].
 //
 // [normalized paths]: https://www.rfc-editor.org/rfc/rfc9535#section-2.7
 func (p *Path) SelectLocated(input any) LocatedNodeList {
@@ -70,13 +71,13 @@ type Parser struct {
 // Option defines a parser option.
 type Option func(*Parser)
 
-// WithRegistry configures a Parser with a function Registry, which may
-// contain function extensions. See [Parser] for an example.
+// WithRegistry configures a [Parser] with a [registry.Registry], which may
+// contain function extensions.
 func WithRegistry(reg *registry.Registry) Option {
 	return func(p *Parser) { p.reg = reg }
 }
 
-// NewParser creates a new Parser configured by opt.
+// NewParser creates a new [Parser] configured by opt.
 func NewParser(opt ...Option) *Parser {
 	p := &Parser{}
 	for _, o := range opt {
@@ -90,20 +91,19 @@ func NewParser(opt ...Option) *Parser {
 	return p
 }
 
-// Parse parses path, a JSON Path query string, into a Path. Returns an
-// ErrPathParse on parse failure.
-//
-//nolint:wrapcheck
+// Parse parses path, a JSONPath query string, into a [Path]. Returns an
+// [ErrPathParse] on parse failure.
 func (c *Parser) Parse(path string) (*Path, error) {
 	q, err := parser.Parse(c.reg, path)
 	if err != nil {
+		//nolint:wrapcheck
 		return nil, err
 	}
 	return New(q), nil
 }
 
-// MustParse parses path, a JSON Path query string, into a Path. Panics with
-// an ErrPathParse on parse failure.
+// MustParse parses path, a JSONPath query string, into a [Path]. Panics with
+// an [ErrPathParse] on parse failure.
 func (c *Parser) MustParse(path string) *Path {
 	q, err := parser.Parse(c.reg, path)
 	if err != nil {
@@ -131,7 +131,7 @@ func (list NodeList) All() iter.Seq[any] {
 }
 
 // LocatedNodeList is a list of nodes selected by a JSONPath query, along with
-// their locations. Returned by [Path.SelectLocated].
+// their [NormalizedPath] locations. Returned by [Path.SelectLocated].
 type LocatedNodeList []*spec.LocatedNode
 
 // All returns an iterator over all the nodes in list.
@@ -147,8 +147,8 @@ func (list LocatedNodeList) All() iter.Seq[*spec.LocatedNode] {
 	}
 }
 
-// Nodes returns an iterator over all the nodes in list. This is effectively
-// the same data a returned by [Path.Select].
+// Nodes returns an iterator over all the nodes in list. This is the same data
+// as returned by [Path.Select].
 func (list LocatedNodeList) Nodes() iter.Seq[any] {
 	return func(yield func(any) bool) {
 		for _, v := range list {
@@ -159,7 +159,7 @@ func (list LocatedNodeList) Nodes() iter.Seq[any] {
 	}
 }
 
-// Paths returns an iterator over all the normalized paths in list.
+// Paths returns an iterator over all the [NormalizedPath] values in list.
 func (list LocatedNodeList) Paths() iter.Seq[spec.NormalizedPath] {
 	return func(yield func(spec.NormalizedPath) bool) {
 		for _, v := range list {
@@ -170,10 +170,10 @@ func (list LocatedNodeList) Paths() iter.Seq[spec.NormalizedPath] {
 	}
 }
 
-// Deduplicate deduplicates the nodes in list based on their normalized paths,
-// modifying the contents of list. It returns the modified list, which may
-// have a smaller length, and zeroes the elements between the new length and
-// the original length.
+// Deduplicate deduplicates the nodes in list based on their [NormalizedPath]
+// values, modifying the contents of list. It returns the modified list, which
+// may have a shorter length, and zeroes the elements between the new length
+// and the original length.
 func (list LocatedNodeList) Deduplicate() LocatedNodeList {
 	if len(list) <= 1 {
 		return list
@@ -192,7 +192,7 @@ func (list LocatedNodeList) Deduplicate() LocatedNodeList {
 	return slices.Clip(uniq)
 }
 
-// Sort sorts list by the normalized path of each node.
+// Sort sorts list by the [NormalizedPath] of each node.
 func (list LocatedNodeList) Sort() {
 	slices.SortFunc(list, func(a, b *spec.LocatedNode) int {
 		return a.Path.Compare(b.Path)

path_example_test.go

@@ -228,13 +228,13 @@ func ExampleParser() {
 	// ["Sayings of the Century","Moby Dick"]
 }
 
-// The second use case for the Parser is to provide a [registry.Registry]
+// Use WithRegistry to create a [Parser] that uses a [registry.Registry]
 // containing function extensions, as [defined by the standard]. This example
 // creates a function named "first" that returns the first item in a list of
 // nodes.
 //
 // [defined by the standard]: https://www.rfc-editor.org/rfc/rfc9535.html#name-function-extensions
-func ExampleParser_functionExtension() {
+func ExampleWithRegistry() {
 	// Register the first function.
 	reg := registry.New()
 	err := reg.Register(
@@ -268,22 +268,22 @@ func ExampleParser_functionExtension() {
 }
 
 // validateFirstArgs validates that a single argument is passed to the first()
-// function, and that it can be converted to [spec.FuncNodes], so that first()
+// function, and that it can be converted to [spec.NodesType], so that first()
 // can return the first node. It's called by the parser.
-func validateFirstArgs(fea []spec.FuncExprArg) error {
-	if len(fea) != 1 {
-		return fmt.Errorf("expected 1 argument but found %v", len(fea))
+func validateFirstArgs(args []spec.FuncExprArg) error {
+	if len(args) != 1 {
+		return fmt.Errorf("expected 1 argument but found %v", len(args))
 	}
 
-	if !fea[0].ResultType().ConvertsToNodes() {
+	if !args[0].ResultType().ConvertsToNodes() {
 		return errors.New("cannot convert argument to nodes")
 	}
 
 	return nil
 }
 
 // firstFunc defines the custom first() JSONPath function. It converts its
-// single argument to a [spec.NodesType] value and returns a [*spec.ValueType]
+// single argument to a [spec.NodesType] value and returns a [spec.ValueType]
 // that contains the first node. If there are no nodes it returns nil.
 func firstFunc(jv []spec.JSONPathValue) spec.JSONPathValue {
 	nodes := spec.NodesFrom(jv[0])

spec/function.go

@@ -67,7 +67,7 @@ func (ft FuncType) ConvertsToNodes() bool {
 	return ft == FuncNodes || ft == FuncSingularQuery
 }
 
-// JSONPathValue defines the interface for JSON path values used as comparison
+// JSONPathValue defines the interface for JSONPath values used as comparison
 // operands, filter expression results, and function parameters & return
 // values.
 //