docs: [api] functions (not resolver methods)

Signed-off-by: Lexus Drumgold <unicornware@flexdevelopment.llc>

Author: unicornware

README.md

@@ -8,8 +8,8 @@ import type { ModuleId } from '@flex-development/mlly'
 /**
  * Check if `input` can be parsed to a {@linkcode URL}.
  *
- * > 👉 **Note**: If `input` is relative, `base` is required. If `input` is
- * > absolute, `base` is ignored.
+ * > 👉 **Note**: If `input` is relative, `base` is required.
+ * > If `input` is absolute, `base` is ignored.
  *
  * @see {@linkcode ModuleId}
  *
@@ -20,7 +20,7 @@ import type { ModuleId } from '@flex-development/mlly'
  * @param {unknown} [base]
  *  The base URL to resolve against if `input` is not absolute
  * @return {boolean}
- *  `true` if `input` can be parsed to a `URL`
+ *  `true` if `input` can be parsed to a `URL`, `false` otherwise
  */
 function canParseUrl(this: void, input: unknown, base?: unknown): boolean {
   try {

src/lib/can-parse-url.mts

@@ -11,8 +11,8 @@ import pathe from '@flex-development/pathe'
  * Check if `value` is an *absolute specifier*.
  *
  * ::: warning
- * Only checks specifier syntax. Does **not** guarantee the specifier references
- * a file that exists.
+ * Only checks specifier syntax.
+ * Does **not** guarantee the specifier references an existing module.
  * :::
  *
  * @see https://nodejs.org/api/esm.html#terminology

src/lib/is-absolute-specifier.mts

@@ -11,8 +11,8 @@ import { isBuiltin } from '@flex-development/is-builtin'
  * Check if `value` is a *bare specifier*.
  *
  * ::: warning
- * Only checks specifier syntax. Does **not** guarantee the specifier references
- * a file that exists.
+ * Only checks specifier syntax.
+ * Does **not** guarantee the specifier references an existing module.
  * :::
  *
  * @see https://nodejs.org/api/esm.html#terminology

src/lib/is-bare-specifier.mts

@@ -7,10 +7,16 @@ import chars from '#internal/chars'
 import type { ImportsSubpath } from '@flex-development/pkg-types'
 
 /**
- * Check if `value` is an `imports` subpath.
+ * Check if `value` is an [`imports`][subpath-imports] subpath.
+ *
+ * ::: warning
+ * Only checks specifier syntax.
+ * Does **not** guarantee the specifier references an existing module.
+ * :::
+ *
+ * [subpath-imports]: https://nodejs.org/api/packages.html#subpath-imports
  *
  * @see {@linkcode ImportsSubpath}
- * @see https://nodejs.org/api/packages.html#subpath-imports
  *
  * @this {void}
  *

src/lib/is-imports-subpath.mts

@@ -6,7 +6,7 @@
 import type { ModuleId } from '@flex-development/mlly'
 
 /**
- * Check if `value` looks like a module id.
+ * Check if `value` is a module id.
  *
  * ::: warning
  * Does **not** guarantee `value` references an existing file or directory.
@@ -19,7 +19,7 @@ import type { ModuleId } from '@flex-development/mlly'
  * @param {unknown} value
  *  The value to check
  * @return {value is ModuleId}
- *  `true` if `value` looks like a module id, `false` otherwise
+ *  `true` if `value` is module id, `false` otherwise
  */
 function isModuleId(this: void, value: unknown): value is ModuleId {
   return typeof value === 'string' || value instanceof URL

src/lib/is-module-id.mts

@@ -9,8 +9,8 @@ import pathe from '@flex-development/pathe'
  * Check if `value` is a *relative specifier*.
  *
  * ::: warning
- * Only checks specifier syntax. Does **not** guarantee the specifier references
- * a file that exists.
+ * Only checks specifier syntax.
+ * Does **not** guarantee the specifier references an existing module.
  * :::
  *
  * @see https://nodejs.org/api/esm.html#terminology

src/lib/is-relative-specifier.mts

@@ -28,12 +28,18 @@ export default lookupPackageScope
  *
  * @param {EmptyString | null | undefined} url
  *  The URL of the module to scope
+ * @param {ModuleId | null | undefined} [end]
+ *  The URL of the directory to end search at, defaults to {@linkcode root}
+ * @param {FileSystem | null | undefined} [fs]
+ *  The file system API
  * @return {null}
  *  The URL of nearest directory containing a `package.json` file
  */
 function lookupPackageScope(
   this: void,
-  url: EmptyString | null | undefined
+  url: EmptyString | null | undefined,
+  end?: ModuleId | null | undefined,
+  fs?: FileSystem | null | undefined
 ): null
 
 /**
@@ -49,7 +55,7 @@ function lookupPackageScope(
  * @see https://github.com/nodejs/node/blob/v22.9.0/doc/api/esm.md#resolution-algorithm-specification
  *
  * @template {Awaitable<URL | null>} T
- *  The resolved URL
+ *  The resolved package scope URL
  *
  * @this {void}
  *

src/lib/lookup-package-scope.mts

@@ -8,11 +8,7 @@ import type { PatternKeyComparison } from '@flex-development/mlly'
 import { ok } from 'devlop'
 
 /**
- * Compare two pattern keys and return a value indicating their order:
- *
- * - `-1`: `a` should come before `b`
- * - `0`: `a` and `b` are equal
- * - `1`: `a` should come after `b`
+ * Compare two pattern keys and return a value indicating their order.
  *
  * Implements the `PATTERN_KEY_COMPARE` algorithm.
  *
@@ -24,9 +20,9 @@ import { ok } from 'devlop'
  * @param {string} a
  *  The first key
  * @param {string} b
- *  The key to compare to `a`
+ *  The key to compare against `a`
  * @return {PatternKeyComparison}
- *  Pattern key comparsion result
+ *  The pattern key comparsion result
  */
 function patternKeyCompare(
   this: void,

src/lib/pattern-key-compare.mts

@@ -16,7 +16,7 @@ import { ok } from 'devlop'
  * @this {void}
  *
  * @param {string} matchKey
- *  The string to expand
+ *  The key to expand
  * @param {unknown} matchObject
  *  The match keys object
  * @return {PatternMatch | null}