docs: add some doc comments [skip ci]

docs/docs/quick-start.md

@@ -4,7 +4,7 @@ This page gets you started using JSONPath, JSON Pointer and JSON Patch with Java
 
 ## JSONPath
 
-Find all values matching a JSONPath query with [`jsonpath.query()`](./api/namespaces/jsonpath.md#query). It takes a string (the query) and some data to apply the query to. It always returns an instance of [`JSONPathNodeList`](./api/classes/jsonpath.JSONPathNodeList.md).
+Find all values matching a JSONPath query with [`jsonpath.query()`](./api/namespaces/jsonpath.md#query). It takes a string (the query) and some data to apply the query to. It always returns an instance of [`JSONPathNodeList`](./api/classes/jsonpath.JSONPathNodeList.md). Use [`JSONPathNodeList.values()`](./api/classes/jsonpath.JSONPathNodeList.md#values) to get an array of values matching the query.
 
 ```javascript
 import { jsonpath } from "json-p3";

src/path/environment.ts

@@ -54,7 +54,10 @@ export type JSONPathEnvironmentOptions = {
 };
 
 /**
+ * A configuration object from which JSONPath queries can be evaluated.
  *
+ * An environment is where you'd register custom function extensions or set
+ * the maximum recursion depth limit, for example.
  */
 export class JSONPathEnvironment {
   /**
@@ -94,8 +97,7 @@ export class JSONPathEnvironment {
   private parser: Parser;
 
   /**
-   *
-   * @param options -
+   * @param options - Environment configuration options.
    */
   constructor(options: JSONPathEnvironmentOptions = {}) {
     this.strict = options.strict ?? true;
@@ -107,9 +109,8 @@ export class JSONPathEnvironment {
   }
 
   /**
-   *
-   * @param path -
-   * @returns
+   * @param path - A JSONPath query to parse.
+   * @returns A new {@link JSONPath} object, bound to this environment.
    */
   public compile(path: string): JSONPath {
     return new JSONPath(
@@ -120,9 +121,10 @@ export class JSONPathEnvironment {
 
   /**
    *
-   * @param path -
-   * @param value -
-   * @returns
+   * @param path - A JSONPath query to parse and evaluate against _value_.
+   * @param value - Data to which _path_ will be applied.
+   * @returns The {@link JSONPathNodeList} resulting from applying _path_
+   * to _value_.
    */
   public query(path: string, value: JSONValue): JSONPathNodeList {
     return this.compile(path).query(value);
@@ -141,6 +143,10 @@ export class JSONPathEnvironment {
     return this.compile(path).match(value);
   }
 
+  /**
+   * A hook for setting up the function register. You are encouraged to
+   * override this method in classes extending `JSONPathEnvironment`.
+   */
   protected setupFilterFunctions(): void {
     this.functionRegister.set("count", new CountFilterFunction());
     this.functionRegister.set("length", new LengthFilterFunction());
@@ -150,9 +156,18 @@ export class JSONPathEnvironment {
   }
 
   /**
+   * Check the well-typedness of a function's arguments at compile-time.
+   *
+   * This method is called by the {@link Parser} when parsing function calls.
+   * It is expected to throw a {@link JSONPathTypeError} if the function's
+   * parameters are not well-typed.
+   *
+   * Override this if you want to deviate from the JSONPath Spec's function
+   * extension type system.
    *
-   * @param token -
-   * @param args -
+   * @param token - The {@link Token} starting the function call. `Token.value`
+   * will contain the name of the function.
+   * @param args - One {@link FilterExpression} for each argument.
    */
   // eslint-disable-next-line sonarjs/cognitive-complexity
   public checkWellTypedness(

src/path/parse.ts

@@ -60,6 +60,9 @@ const BINARY_OPERATORS: Map<TokenKind, string> = new Map([
 
 const COMPARISON_OPERATORS = new Set(["==", ">=", ">", "<=", "<", "!="]);
 
+/**
+ * JSONPath token stream parser.
+ */
 export class Parser {
   protected tokenMap: Map<string, (stream: TokenStream) => FilterExpression>;