Improve comments

src/config/normalize/lib/star_dot_path/tokens/any.js

@@ -3,22 +3,24 @@ import isPlainObj from 'is-plain-obj'
 import { isRecurseObject } from './recurse.js'
 import { ANY, ESCAPE, SEPARATOR } from './special.js'
 
-// Check if a token is *
+// Check the type of a parsed token
 const testObject = function (token) {
   return isPlainObj(token) && token.type === ANY_TYPE
 }
 
 const ANY_TYPE = 'any'
 
+// Serialize a token to a string
 const serialize = function () {
   return ANY
 }
 
+// Check the type of a serialized token
 const testString = function ({ hasAny }) {
   return hasAny
 }
 
-// Parse a * string into a token
+// Parse a string into a token
 const parse = function (chars) {
   if (chars !== ANY) {
     throw new Error(
@@ -31,12 +33,13 @@ Otherwise, please escape it with a "${ESCAPE}".`,
   return { type: ANY_TYPE }
 }
 
+// When the token is missing a target value, add a default one.
 // When missing, there are no entries, so no need to add missing entries.
 const handleMissingValue = function (value) {
   return { value, missing: false }
 }
 
-// List entries when using *, e.g. `a.*`
+// Use the token to list entries against a target value.
 // We purposely ignore symbol properties by using `Object.keys()`.
 const getEntries = function (value, path) {
   if (Array.isArray(value)) {

src/config/normalize/lib/star_dot_path/tokens/array.js

@@ -1,43 +1,38 @@
 import { MINUS } from './special.js'
 
-// Users can specify integers either:
-//  - stringified for object properties
-//  - left as is for array indices
-// At query string parsing time, without any target value, we assume the intent
-// was for arrays.
-// We allow negative indexes which query from the end
-//  - Including -0 which can be used to append values
-// Check if token is an array index integer
+// Check the type of a parsed token.
+// Integers specified as string tokens are assumed to be property names, not
+// array indices.
 const testObject = function (token) {
   return Number.isInteger(token)
 }
 
-// Serialize an array index token into a string
+// Serialize a token to a string
 const serialize = function (token) {
   return Object.is(token, -0) ? '-0' : String(token)
 }
 
-// Check if a string should be parsed as an index token
+// Check the type of a serialized token
 const testString = function ({ chars, hasMinus }) {
   const hasEscapedMinus = chars[0] === MINUS && !hasMinus
   return !hasEscapedMinus && INTEGER_REGEXP.test(chars)
 }
 
 const INTEGER_REGEXP = /^-?\d+$/u
 
-// Parse an array index string into a token
+// Parse a string into a token
 const parse = function (chars) {
   return Number(chars)
 }
 
-// Default array when missing
+// When the token is missing a target value, add a default one.
 const handleMissingValue = function (value) {
   const missing = !Array.isArray(value)
   const valueA = missing ? [] : value
   return { value: valueA, missing }
 }
 
-// List entries when using indices, e.g. `a.1`
+// Use the token to list entries against a target value.
 const getEntries = function (value, path, token) {
   const index = getArrayIndex(value, token)
   return [{ value: value[index], path: [...path, index] }]

src/config/normalize/lib/star_dot_path/tokens/prop.js

@@ -2,33 +2,34 @@ import { escapeSpecialChars } from './escape.js'
 import { isRecurseObject } from './recurse.js'
 import { SEPARATOR } from './special.js'
 
-// Check if a token is a property name string
+// Check the type of a parsed token
 const testObject = function (token) {
   return typeof token === 'string'
 }
 
-// Serialize a property token into a string
+// Serialize a token to a string
 const serialize = function (token, index) {
   return token === '' && index === 0 ? SEPARATOR : escapeSpecialChars(token)
 }
 
+// Check the type of a serialized token
 const testString = function () {
   return true
 }
 
-// Parse a property string into a token
+// Parse a string into a token
 const parse = function (chars) {
   return chars
 }
 
-// Default object when missing
+// When the token is missing a target value, add a default one.
 const handleMissingValue = function (value) {
   const missing = !isRecurseObject(value)
   const valueA = missing ? {} : value
   return { value: valueA, missing }
 }
 
-// List entries when using property names, e.g. `a.b`
+// Use the token to list entries against a target value.
 const getEntries = function (value, path, token) {
   return [{ value: value[token], path: [...path, token] }]
 }

src/config/normalize/lib/star_dot_path/tokens/regexp.js

@@ -2,22 +2,23 @@ import { escapeSpecialChars } from './escape.js'
 import { isRecurseObject } from './recurse.js'
 import { REGEXP_DELIM } from './special.js'
 
-// Check if a token is a /.../ RegExp
+// Check the type of a parsed token
 const testObject = function (token) {
   return token instanceof RegExp
 }
 
-// Serialize a RegExp token into a string
+// Serialize a token to a string
 const serialize = function (token) {
   const source = escapeSpecialChars(token.source)
   return `${REGEXP_DELIM}${source}${REGEXP_DELIM}${token.flags}`
 }
 
+// Check the type of a serialized token
 const testString = function ({ hasRegExp }) {
   return hasRegExp
 }
 
-// Parse a RegExp string into a token.
+// Parse a string into a token
 // This might throw if the RegExp is invalid.
 const parse = function (chars) {
   const endIndex = chars.lastIndexOf(REGEXP_DELIM)
@@ -33,12 +34,13 @@ const parse = function (chars) {
   return new RegExp(regExpString, regExpFlags)
 }
 
+// When the token is missing a target value, add a default one.
 // When missing, there are no entries, so no need to add missing entries.
 const handleMissingValue = function (value) {
   return { value, missing: false }
 }
 
-// List entries when using RegExps, e.g. `a./[bc]/`
+// Use the token to list entries against a target value.
 const getEntries = function (value, path, token) {
   if (!isRecurseObject(value)) {
     return []