Add docs to types

Author: wooorm

index.js

@@ -8,28 +8,57 @@ import {any} from './lib/any.js'
 import {parse} from './lib/parse.js'
 
 /**
+ * Check that the given `node` matches `selector`.
+ *
+ * This only checks the node itself, not the surrounding tree.
+ * Thus, nesting in selectors is not supported (`paragraph strong`,
+ * `paragraph > strong`), neither are selectors like `:first-child`, etc.
+ * This only checks that the given node matches the selector.
+ *
  * @param {string} selector
- * @param {NodeLike|Node} [node]
+ *   CSS selector, such as (`heading`, `link, linkReference`).
+ * @param {Node | NodeLike | undefined} [node]
+ *   Node that might match `selector`.
  * @returns {boolean}
+ *   Whether `node` matches `selector`.
  */
 export function matches(selector, node) {
   return Boolean(any(parse(selector), node, {one: true, shallow: true, any})[0])
 }
 
 /**
+ * Select the first node that matches `selector` in the given `tree`.
+ *
+ * Searches the tree in *preorder*.
+ *
  * @param {string} selector
- * @param {NodeLike|Node} [node]
- * @returns {Node|null}
+ *   CSS selector, such as (`heading`, `link, linkReference`).
+ * @param {Node | NodeLike | undefined} [tree]
+ *   Tree to search.
+ * @returns {Node | null}
+ *   First node in `tree` that matches `selector` or `null` if nothing is
+ *   found.
+ *
+ *   This could be `tree` itself.
  */
-export function select(selector, node) {
-  return any(parse(selector), node, {one: true, any})[0] || null
+export function select(selector, tree) {
+  return any(parse(selector), tree, {one: true, any})[0] || null
 }
 
 /**
+ * Select all nodes that match `selector` in the given `tree`.
+ *
+ * Searches the tree in *preorder*.
+ *
  * @param {string} selector
- * @param {NodeLike|Node} [node]
+ *   CSS selector, such as (`heading`, `link, linkReference`).
+ * @param {Node | NodeLike | undefined} [tree]
+ *   Tree to search.
  * @returns {Array<Node>}
+ *   Nodes in `tree` that match `selector`.
+ *
+ *   This could include `tree` itself.
  */
-export function selectAll(selector, node) {
-  return any(parse(selector), node, {any})
+export function selectAll(selector, tree) {
+  return any(parse(selector), tree, {any})
 }

lib/types.js

@@ -1,4 +1,7 @@
 /**
+ * @typedef {import('unist').Node} Node
+ * @typedef {import('unist').Parent} Parent
+ *
  * @typedef {import('css-selector-parser').Selector} Selector
  * @typedef {import('css-selector-parser').Selectors} Selectors
  * @typedef {import('css-selector-parser').RuleSet} RuleSet
@@ -7,29 +10,26 @@
  * @typedef {import('css-selector-parser').AttrValueType} AttrValueType
  * @typedef {Selector|Rule|RulePseudo} Query
  *
- * Fix for types.
- * @typedef {Object} RuleAttr
+ * @typedef RuleAttr
+ *   Fix for types from `css-selector-parser`.
  * @property {string} name
  * @property {string} [operator]
  * @property {AttrValueType} [valueType]
  * @property {string} [value]
  *
- * More specific type for registered selector pseudos.
- * @typedef {Object} RulePseudoSelector
+ * @typedef RulePseudoSelector
+ *   More specific type for registered selector pseudos.
  * @property {string} name
  * @property {'selector'} valueType
  * @property {Selector} value
  *
- * Overwrite to compile nth-checks once.
- * @typedef {Object} RulePseudoNth
+ * @typedef RulePseudoNth
+ *   Overwrite to compile nth-checks once.
  * @property {string} name
  * @property {'function'} valueType
  * @property {(index: number) => boolean} value
  *
- * @typedef {import('unist').Node} Node
- * @typedef {import('unist').Parent} Parent
- *
- * @typedef {Object} SelectState
+ * @typedef SelectState
  * @property {(query: Selectors|RuleSet|Rule, node: Node|undefined, state: SelectState) => Node[]} any
  * @property {SelectIterator|null|undefined} [iterator]
  * @property {Array<Node>} [scopeNodes]

readme.md

@@ -35,13 +35,25 @@ There is no default export.
 
 ### `matches(selector, node)`
 
-Check that the given [node][] matches `selector`.
-Returns `boolean`, whether the node matches or not.
+Check that the given `node` matches `selector`.
 
-This only checks the element itself, not the surrounding tree.
+This only checks the node itself, not the surrounding tree.
 Thus, nesting in selectors is not supported (`paragraph strong`,
-`paragraph > strong`), nor are selectors like `:first-child`, etc.
-This only checks that the given element matches the selector.
+`paragraph > strong`), neither are selectors like `:first-child`, etc.
+This only checks that the given node matches the selector.
+
+###### Parameters
+
+*   `selector` (`string`)
+    — CSS selector, such as (`heading`, `link, linkReference`).
+*   `node` ([`Node`][node], optional)
+    — node that might match `selector`
+
+###### Returns
+
+Whether `node` matches `selector` (`boolean`).
+
+###### Example
 
 ```js
 import {u} from 'unist-builder'
@@ -53,9 +65,24 @@ matches('[lang]', u('code', {lang: 'js'}, 'console.log(1)')) // => true
 
 ### `select(selector, tree)`
 
-Select the first node matching `selector` in the given `tree` (could be the
-tree itself).
-Returns the found [node][], if any.
+Select the first node that matches `selector` in the given `tree`.
+
+Searches the tree in *[preorder][]*.
+
+###### Parameters
+
+*   `selector` (`string`)
+    — CSS selector, such as (`heading`, `link, linkReference`).
+*   `tree` ([`Node`][node], optional)
+    — tree to search
+
+###### Returns
+
+First node in `tree` that matches `selector` or `null` if nothing is found.
+
+This could be `tree` itself.
+
+###### Example
 
 ```js
 import {u} from 'unist-builder'
@@ -83,9 +110,24 @@ Yields:
 
 ### `selectAll(selector, tree)`
 
-Select all nodes matching `selector` in the given `tree` (could include the
-tree itself).
-Returns all found [node][]s, if any.
+Select all nodes that match `selector` in the given `tree`.
+
+Searches the tree in *[preorder][]*.
+
+###### Parameters
+
+*   `selector` (`string`)
+    — CSS selector, such as (`heading`, `link, linkReference`).
+*   `tree` ([`Node`][node], optional)
+    — tree to search
+
+###### Returns
+
+Nodes in `tree` that match `selector`.
+
+This could include `tree` itself.
+
+###### Example
 
 ```js
 import {u} from 'unist-builder'
@@ -232,6 +274,8 @@ abide by its terms.
 
 [coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md
 
+[preorder]: https://github.com/syntax-tree/unist#preorder
+
 [unist]: https://github.com/syntax-tree/unist
 
 [node]: https://github.com/syntax-tree/unist#node