Refactor docs

lib/index.js

@@ -20,75 +20,115 @@
  *
  * @typedef Marker
  *   Comment marker.
+ *
+ *   ###### Notes
+ *
+ *   The **disable** keyword turns off messages.
+ *   For example:
+ *
+ *   ```markdown
+ *   <!--lint disable list-item-bullet-indent strong-marker-->
+ *
+ *   *   **foo**
+ *
+ *   A paragraph, and now another list.
+ *
+ *     * __bar__
+ *   ```
+ *
+ *   The **enable** keyword turns on messages.
+ *   For example:
+ *
+ *   ```markdown
+ *   <!--lint enable strong-marker-->
+ *
+ *   **foo** and __bar__.
+ *   ```
+ *
+ *   The **ignore** keyword turns off messages in the following node.
+ *   After the end of the following node, messages are turned on again.
+ *   For example:
+ *
+ *   ```markdown
+ *   <!--lint ignore list-item-bullet-indent strong-marker-->
+ *
+ *   *   **foo**
+ *       * __bar__
+ *   ```
+ *
  * @property {string} name
  *   Name of marker.
  * @property {string} attributes
- *   Value after name.
- * @property {Record<string, boolean | number | string>} parameters
- *   Parsed attributes.
- * @property {Node} node
- *   Reference to given node.
+ *   Raw values (space-separated); the first should be `enable`, `disable`, or
+    `ignore`, the rest are optional rule identifiers.
  *
  * @callback MarkerParser
- *   Parse a possible comment marker node to a Marker.
+ *   Parse a possible comment marker.
  * @param {Node} node
- *   Node to parse
+ *   Potential marker.
  * @returns {Marker | null | undefined | void}
- *   Result.
+ *   Marker.
  *
  * @typedef Options
- *   Regular fields.
- * @property {Array<string> | null | undefined} [enable]
- *   List of `ruleId`s to initially turn on (default: `[]`); used if `reset` is
- *   `true`.
- * @property {Array<string> | null | undefined} [disable]
- *   List of `ruleId`s to turn off (default: `[]`); used if `reset` is not
- *   `true`.
- * @property {Array<string> | null | undefined} [known]
- *   List of allowed `ruleId`s (default: `[]`).
+ *   Configuration.
  *
- *   When `known` is given, a warning is shown when unknown rules are
- *   controlled with comments.
+ *   ###### Notes
+ *
+ *   The given `name` defines which comments work.
+ *   Assuming there’s a `marker` configured that parses HTML comments such as
+ *   `<!--x y z-->` to a mark with `name: 'x'`, then giving `name: 'x'` will
+ *   use comments such as:
+ *
+ *   ```html
+ *   <!--alpha ignore-->
+ *   ```
  *
+ *   When `known` is given, a warning is shown when unknown rules are
+ *   controlled.
  *   For example, `{name: 'alpha', known: ['bravo']}` results in a warning
  *   (for `charlie`):
  *
  *   ```html
  *   <!--alpha ignore charlie-->
  *   ```
+ * @property {Array<string> | null | undefined} [enable]
+ *   List of `ruleId`s to initially turn on (optional); used if `reset` is
+ *   `true`.
+ * @property {Array<string> | null | undefined} [disable]
+ *   List of `ruleId`s to turn off (optional); used if `reset` is not
+ *   `true`.
+ * @property {Array<string> | null | undefined} [known]
+ *   List of allowed `ruleId`s (optional).
  * @property {VFile} file
  *   Corresponding file (required).
  * @property {MarkerParser} marker
  *   Parse nodes to `Marker` objects (required).
  * @property {string} name
  *   Name of markers that can control the message sources (required).
- *
- *   For example, `{name: 'alpha'}` controls `alpha` markers:
- *
- *   ```html
- *   <!--alpha ignore-->
- *   ```
  * @property {boolean | null | undefined} [reset]
  *   Whether to treat all messages as turned off initially.
  * @property {Array<string> | string | null | undefined} [source]
- *   Sources that can be controlled with `name` markers (default: `name`).
+ *   Sources that can be controlled with markers (default: `options.name`).
  * @property {Test} [test]
  *   Test for possible markers (optional).
  */
 
 import {ok as assert} from 'devlop'
+import {parse as spaceSeparated} from 'space-separated-tokens'
 import {visit} from 'unist-util-visit'
 import {location} from 'vfile-location'
 
 const own = {}.hasOwnProperty
 
 /**
+ * Let comment markers control messages.
+ *
  * @param {Node} tree
  *   Tree.
  * @param {Options} options
  *   Configuration (required).
- * @returns
- *   Transform.
+ * @returns {undefined}
+ *   Nothing.
  */
 export function messageControl(tree, options) {
   if (!options || typeof options !== 'object') {
@@ -147,7 +187,7 @@ export function messageControl(tree, options) {
       return
     }
 
-    const ruleIds = mark.attributes.split(/\s+/g)
+    const ruleIds = spaceSeparated(mark.attributes)
     const verb = ruleIds.shift()
     const fn =
       verb === 'enable'
@@ -164,7 +204,7 @@ export function messageControl(tree, options) {
           verb +
           '`: expected ' +
           "`'enable'`, `'disable'`, or `'ignore'`",
-        mark.node
+        node
       )
     }
 
@@ -185,7 +225,7 @@ export function messageControl(tree, options) {
       while (++index < ruleIds.length) {
         const ruleId = ruleIds[index]
 
-        if (isKnown(ruleId, verb, mark.node)) {
+        if (isKnown(ruleId, verb, node)) {
           fn(point, ruleId, tail)
         }
       }

package.json

@@ -34,6 +34,7 @@
   "dependencies": {
     "@types/unist": "^3.0.0",
     "devlop": "^1.0.0",
+    "space-separated-tokens": "^2.0.0",
     "unist-util-is": "^6.0.0",
     "unist-util-visit": "^5.0.0",
     "vfile": "^6.0.0",