Refactor docs

Author: wooorm

packages/hast-util-from-string/index.js

@@ -46,12 +46,6 @@
  *
  * Set the plain-text value of a node.
  *
- * *   if `node` is a text node (has a `value` property; as in, `comment`,
- *     `text`), set that to the given `value` or an empty string
- * *   Otherwise, if `node` is a parent node (has `children`; as in, `element`,
- *     `root`), replace them with a text node whose data is set to the given
- *     `value`, or if `value` is not given, remove all its children
- *
  * ###### Parameters
  *
  * *   `node` (`Node`) — node to change
@@ -60,6 +54,12 @@
  * ###### Returns
  *
  * Nothing (`undefined`).
+ *
+ * ###### Algorithm
+ *
+ * *   if `node` is a `comment` or `text` node, sets its `value`
+ * *   if `node` is an `element` or `root`, replaces its children with a text
+ *     node for `value`
  */
 
 export {fromString} from './lib/index.js'

packages/hast-util-from-string/lib/index.js

@@ -4,6 +4,7 @@
 
 /**
  * Set the plain-text value of a hast node.
+ *
  * This is like the DOMs `Node#textContent` setter.
  * The given node is returned.
  *

packages/hast-util-from-string/readme.md

@@ -92,20 +92,14 @@ console.log(div)
 
 ## API
 
-This package exports the following identifiers:
+This package exports the identifier
 `fromString`.
 There is no default export.
 
 ### `fromString(node[, value])`
 
 Set the plain-text value of a node.
 
-*   if `node` is a text node (has a `value` property; as in, `comment`,
-    `text`), set that to the given `value` or an empty string
-*   Otherwise, if `node` is a parent node (has `children`; as in, `element`,
-    `root`), replace them with a text node whose data is set to the given
-    `value`, or if `value` is not given, remove all its children
-
 ###### Parameters
 
 *   `node` (`Node`) — node to change
@@ -115,25 +109,35 @@ Set the plain-text value of a node.
 
 Nothing (`undefined`).
 
+###### Algorithm
+
+*   if `node` is a `comment` or `text` node, sets its `value`
+*   if `node` is an `element` or `root`, replaces its children with a text
+    node for `value`
+
 ## Syntax
 
-HTML is handled according to WHATWG HTML (the living standard), which is also
-followed by browsers such as Chrome and Firefox.
+HTML is parsed according to WHATWG HTML (the living standard), which is also
+followed by all browsers.
 
 ## Syntax tree
 
-The syntax tree format used is [`hast`][hast].
+The syntax tree used is [hast][].
 
 ## Types
 
 This package is fully typed with [TypeScript][].
 
 ## Compatibility
 
-Projects maintained by the unified collective are compatible with all maintained
+Projects maintained by the unified collective are compatible with maintained
 versions of Node.js.
-As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
-Our projects sometimes work with older versions, but this is not guaranteed.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`hast-util-from-string@^2`,
+compatible with Node.js 12.
 
 ## Security
 
@@ -197,9 +201,9 @@ abide by its terms.
 
 [rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize
 
-[size]: https://bundlephobia.com/result?p=hast-util-from-string
+[size]: https://bundlejs.com/?q=hast-util-from-string
 
-[size-badge]: https://img.shields.io/bundlephobia/minzip/hast-util-from-string.svg
+[size-badge]: https://img.shields.io/bundlejs/size/hast-util-from-string
 
 [support]: https://github.com/rehypejs/.github/blob/main/support.md
 

packages/hast-util-is-body-ok-link/index.js

@@ -28,13 +28,15 @@
  *
  * Check whether a node is a “body OK” link.
  *
- * *   returns `true` for `link` elements with an `itemProp`
- * *   returns `true` for `link` elements with a `rel` list where one or more
- *     entries are `pingback`, `prefetch`, or `stylesheet`
+ * The following nodes are “body OK” links:
+ *
+ * *   `link` elements with an `itemProp`
+ * *   `link` elements with a `rel` list where one or more entries are
+ *     `pingback`, `prefetch`, or `stylesheet`
  *
  * ###### Parameters
  *
- * *   `node` (`Node`) — hast node
+ * *   `node` (`Node`) — node to check.
  *
  * ###### Returns
  *

packages/hast-util-is-body-ok-link/readme.md

@@ -74,45 +74,51 @@ isBodyOkLink(h('link', {rel: ['author'], href: 'index.css'})) //=> false
 
 ## API
 
-This package exports the following identifiers:
+This package exports the identifier
 `isBodyOkLink`.
 There is no default export.
 
 ### `isBodyOkLink(node)`
 
 Check whether a node is a “body OK” link.
 
-*   returns `true` for `link` elements with an `itemProp`
-*   returns `true` for `link` elements with a `rel` list where one or more
-    entries are `pingback`, `prefetch`, or `stylesheet`
+The following nodes are “body OK” links:
+
+*   `link` elements with an `itemProp`
+*   `link` elements with a `rel` list where one or more entries are
+    `pingback`, `prefetch`, or `stylesheet`
 
 ###### Parameters
 
-*   `node` (`Node`) — hast node
+*   `node` (`Node`) — node to check.
 
 ###### Returns
 
 Whether a node is a “body OK” link (`boolean`).
 
 ## Syntax
 
-HTML is handled according to WHATWG HTML (the living standard), which is also
-followed by browsers such as Chrome and Firefox.
+HTML is parsed according to WHATWG HTML (the living standard), which is also
+followed by all browsers.
 
 ## Syntax tree
 
-The syntax tree format used is [`hast`][hast].
+The syntax tree used is [hast][].
 
 ## Types
 
 This package is fully typed with [TypeScript][].
 
 ## Compatibility
 
-Projects maintained by the unified collective are compatible with all maintained
+Projects maintained by the unified collective are compatible with maintained
 versions of Node.js.
-As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
-Our projects sometimes work with older versions, but this is not guaranteed.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`hast-util-is-body-ok-link@^2`,
+compatible with Node.js 12.
 
 ## Security
 
@@ -176,9 +182,9 @@ abide by its terms.
 
 [rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize
 
-[size]: https://bundlephobia.com/result?p=hast-util-is-body-ok-link
+[size]: https://bundlejs.com/?q=hast-util-is-body-ok-link
 
-[size-badge]: https://img.shields.io/bundlephobia/minzip/hast-util-is-body-ok-link.svg
+[size-badge]: https://img.shields.io/bundlejs/size/hast-util-is-body-ok-link
 
 [support]: https://github.com/rehypejs/.github/blob/main/support.md
 

packages/hast-util-is-conditional-comment/index.js

@@ -33,7 +33,7 @@
  *
  * ###### Parameters
  *
- * *   `node` (`Node`) — hast node
+ * *   `node` (`Node`) — node to check
  *
  * ###### Returns
  *

packages/hast-util-is-conditional-comment/lib/index.js

@@ -1,9 +1,9 @@
-const re = /^\[if[ \t\f\n\r]+[^\]]+]|<!\[endif]$/
-
 /**
  * @typedef {import('hast').Nodes} Nodes
  */
 
+const re = /^\[if[ \t\f\n\r]+[^\]]+]|<!\[endif]$/
+
 /**
  * Check if a node is a conditional comment.
  *

packages/hast-util-is-conditional-comment/readme.md

@@ -77,7 +77,7 @@ isConditionalComment(u({type: 'comment', value: 'foo'})) //=> false
 
 ## API
 
-This package exports the following identifiers:
+This package exports the identifier
 `isConditionalComment`.
 There is no default export.
 
@@ -87,31 +87,35 @@ Check if a node is a conditional comment.
 
 ###### Parameters
 
-*   `node` (`Node`) — hast node
+*   `node` (`Node`) — node to check
 
 ###### Returns
 
 Whether a node is a conditional comment (`boolean`).
 
 ## Syntax
 
-HTML is handled according to WHATWG HTML (the living standard), which is also
-followed by browsers such as Chrome and Firefox.
+HTML is parsed according to WHATWG HTML (the living standard), which is also
+followed by all browsers.
 
 ## Syntax tree
 
-The syntax tree format used is [`hast`][hast].
+The syntax tree used is [hast][].
 
 ## Types
 
 This package is fully typed with [TypeScript][].
 
 ## Compatibility
 
-Projects maintained by the unified collective are compatible with all maintained
+Projects maintained by the unified collective are compatible with maintained
 versions of Node.js.
-As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
-Our projects sometimes work with older versions, but this is not guaranteed.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`hast-util-is-conditional-comment@^2`,
+compatible with Node.js 12.
 
 ## Security
 
@@ -175,9 +179,9 @@ abide by its terms.
 
 [rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize
 
-[size]: https://bundlephobia.com/result?p=hast-util-is-conditional-comment
+[size]: https://bundlejs.com/?q=hast-util-is-conditional-comment
 
-[size-badge]: https://img.shields.io/bundlephobia/minzip/hast-util-is-conditional-comment.svg
+[size-badge]: https://img.shields.io/bundlejs/size/hast-util-is-conditional-comment
 
 [support]: https://github.com/rehypejs/.github/blob/main/support.md
 

packages/hast-util-is-css-link/index.js

@@ -34,7 +34,7 @@
  *
  * ###### Parameters
  *
- * *   `node` (`Node`) — hast node
+ * *   `node` (`Node`) — node to check
  *
  * ###### Returns
  *

packages/hast-util-is-css-link/lib/index.js

@@ -7,6 +7,10 @@ import {collapseWhiteSpace} from 'collapse-white-space'
 /**
  * Check whether a hast node is a `<link>` that references CSS.
  *
+ * Returns `true` if `node` is a `<link>` element with a `rel` list that
+ * contains `'stylesheet'` and has no `type`, an empty `type`, or `'text/css'`
+ * as its `type`.
+ *
  * @param {Nodes} node
  *   Node to check.
  * @returns {boolean}