Refactor docs

lib/index.js

@@ -60,19 +60,35 @@ export function createLowlight(grammars) {
   /**
    * Highlight `value` (code) as `language` (name).
    *
+   * @example
+   *   ```js
+   *   import {common, createLowlight} from 'lowlight'
+   *
+   *   const lowlight = createLowlight(common)
+   *
+   *   console.log(lowlight.highlight('css', 'em { color: red }'))
+   *   ```
+   *
+   *   Yields:
+   *
+   *   ```js
+   *   {type: 'root', children: [Array], data: {language: 'css', relevance: 3}}
+   *   ```
+   *
    * @param {string} language
    *   Programming language name.
    * @param {string} value
    *   Code to highlight.
    * @param {Readonly<Options> | null | undefined} [options={}]
    *   Configuration (optional).
    * @returns {Root}
-   *   A hast `Root` node.
+   *   Tree; with the following `data` fields: `language` (`string`), detected
+   *   programming language name; `relevance` (`number`), how sure lowlight is
+   *   that the given code is in the language.
    */
   function highlight(language, value, options) {
     assert(typeof language === 'string', 'expected `string` as `name`')
     assert(typeof value === 'string', 'expected `string` as `value`')
-
     const settings = options || emptyOptions
     const prefix =
       typeof settings.prefix === 'string' ? settings.prefix : defaultPrefix
@@ -112,23 +128,39 @@ export function createLowlight(grammars) {
   /**
    * Highlight `value` (code) and guess its programming language.
    *
+   * @example
+   *   ```js
+   *   import {common, createLowlight} from 'lowlight'
+   *
+   *   const lowlight = createLowlight(common)
+   *
+   *   console.log(lowlight.highlightAuto('"hello, " + name + "!"'))
+   *   ```
+   *
+   *   Yields:
+   *
+   *   ```js
+   *   {type: 'root', children: [Array], data: {language: 'arduino', relevance: 2}}
+   *   ```
+   *
    * @param {string} value
    *   Code to highlight.
    * @param {Readonly<AutoOptions> | null | undefined} [options={}]
    *   Configuration (optional).
    * @returns {Root}
-   *   A hast `Root` node.
+   *   Tree; with the following `data` fields: `language` (`string`), detected
+   *   programming language name; `relevance` (`number`), how sure lowlight is
+   *   that the given code is in the language.
    */
   function highlightAuto(value, options) {
     assert(typeof value === 'string', 'expected `string` as `value`')
-
     const settings = options || emptyOptions
     const subset = settings.subset || listLanguages()
 
     let index = -1
     let relevance = 0
-    /** @type {Root} */
-    let result = {type: 'root', children: []}
+    /** @type {Root | undefined} */
+    let result
 
     while (++index < subset.length) {
       const name = subset[index]
@@ -147,16 +179,32 @@ export function createLowlight(grammars) {
       }
     }
 
-    if (!result.data) {
-      result.data = {language: undefined, relevance}
-    }
-
-    return result
+    return (
+      result || {
+        type: 'root',
+        children: [],
+        data: {language: undefined, relevance}
+      }
+    )
   }
 
   /**
    * List registered languages.
    *
+   * @example
+   *   ```js
+   *   import {createLowlight} from 'lowlight'
+   *   import markdown from 'highlight.js/lib/languages/markdown'
+   *
+   *   const lowlight = createLowlight()
+   *
+   *   console.log(lowlight.listLanguages()) // => []
+   *
+   *   lowlight.register({markdown})
+   *
+   *   console.log(lowlight.listLanguages()) // => ['markdown']
+   *   ```
+   *
    * @returns {Array<string>}
    *   Names of registered language.
    */
@@ -167,33 +215,52 @@ export function createLowlight(grammars) {
   /**
    * Register languages.
    *
+   * @example
+   *   ```js
+   *   import {createLowlight} from 'lowlight'
+   *   import xml from 'highlight.js/lib/languages/xml'
+   *
+   *   const lowlight = createLowlight()
+   *
+   *   lowlight.register({xml})
+   *
+   *   // Note: `html` is an alias for `xml`.
+   *   console.log(lowlight.highlight('html', '<em>Emphasis</em>'))
+   *   ```
+   *
+   *   Yields:
+   *
+   *   ```js
+   *   {type: 'root', children: [Array], data: {language: 'html', relevance: 2}}
+   *   ```
+   *
    * @overload
-   * @param {Readonly<Record<string, LanguageFn>>} languageMap
+   * @param {Readonly<Record<string, LanguageFn>>} grammars
    * @returns {undefined}
    *
    * @overload
    * @param {string} name
-   * @param {LanguageFn} language
+   * @param {LanguageFn} grammar
    * @returns {undefined}
    *
-   * @param {Readonly<Record<string, LanguageFn>> | string} languageMapOrName
-   *   Programming language name or a map of names to language functions.
-   * @param {LanguageFn | undefined} [languageFn]
-   *   Language function, if with name.
+   * @param {Readonly<Record<string, LanguageFn>> | string} grammarsOrName
+   *   Grammars or programming language name.
+   * @param {LanguageFn | undefined} [grammar]
+   *   Grammar, if with name.
    * @returns {undefined}
    *   Nothing.
    */
-  function register(languageMapOrName, languageFn) {
-    if (typeof languageMapOrName === 'string') {
-      assert(languageFn !== undefined, 'expected `languageFn`')
-      high.registerLanguage(languageMapOrName, languageFn)
+  function register(grammarsOrName, grammar) {
+    if (typeof grammarsOrName === 'string') {
+      assert(grammar !== undefined, 'expected `grammar`')
+      high.registerLanguage(grammarsOrName, grammar)
     } else {
       /** @type {string} */
       let name
 
-      for (name in languageMapOrName) {
-        if (Object.hasOwn(languageMapOrName, name)) {
-          high.registerLanguage(name, languageMapOrName[name])
+      for (name in grammarsOrName) {
+        if (Object.hasOwn(grammarsOrName, name)) {
+          high.registerLanguage(name, grammarsOrName[name])
         }
       }
     }
@@ -202,37 +269,55 @@ export function createLowlight(grammars) {
   /**
    * Register aliases.
    *
+   * @example
+   *   ```js
+   *   import {createLowlight} from 'lowlight'
+   *   import markdown from 'highlight.js/lib/languages/markdown'
+   *
+   *   const lowlight = createLowlight()
+   *
+   *   lowlight.register({markdown})
+   *
+   *   // lowlight.highlight('mdown', '<em>Emphasis</em>')
+   *   // ^ would throw: Error: Unknown language: `mdown` is not registered
+   *
+   *   lowlight.registerAlias({markdown: ['mdown', 'mkdn', 'mdwn', 'ron']})
+   *   lowlight.highlight('mdown', '<em>Emphasis</em>')
+   *   // ^ Works!
+   *   ```
+   *
    * @overload
-   * @param {Readonly<Record<string, ReadonlyArray<string> | string>>} aliaseMap
+   * @param {Readonly<Record<string, ReadonlyArray<string> | string>>} aliases
    * @returns {undefined}
    *
    * @overload
    * @param {string} language
-   * @param {ReadonlyArray<string> | string} aliases
+   * @param {ReadonlyArray<string> | string} alias
    * @returns {undefined}
    *
-   * @param {Readonly<Record<string, ReadonlyArray<string> | string>> | string} language
-   *   Programming language name or a map of `language`s to `alias`es or `list`s
+   * @param {Readonly<Record<string, ReadonlyArray<string> | string>> | string} aliasesOrName
+   *   Map of programming language names to one or more aliases, or programming
+   *   language name.
    * @param {ReadonlyArray<string> | string | undefined} [alias]
-   *   New aliases for the programming language.
+   *   One or more aliases for the programming language, if with `name`.
    * @returns {undefined}
    *   Nothing.
    */
-  function registerAlias(language, alias) {
-    if (typeof language === 'string') {
+  function registerAlias(aliasesOrName, alias) {
+    if (typeof aliasesOrName === 'string') {
       assert(alias !== undefined)
       high.registerAliases(
         // Note: copy needed because hljs doesn’t accept readonly arrays yet.
         typeof alias === 'string' ? alias : [...alias],
-        {languageName: language}
+        {languageName: aliasesOrName}
       )
     } else {
       /** @type {string} */
       let key
 
-      for (key in language) {
-        if (Object.hasOwn(language, key)) {
-          const aliases = language[key]
+      for (key in aliasesOrName) {
+        if (Object.hasOwn(aliasesOrName, key)) {
+          const aliases = aliasesOrName[key]
           high.registerAliases(
             // Note: copy needed because hljs doesn’t accept readonly arrays yet.
             typeof aliases === 'string' ? aliases : [...aliases],
@@ -244,15 +329,28 @@ export function createLowlight(grammars) {
   }
 
   /**
-   * Check whether an `alias` or `language` is registered.
+   * Check whether an alias or name is registered.
+   *
+   * @example
+   *   ```js
+   *   import {createLowlight} from 'lowlight'
+   *   import javascript from 'highlight.js/lib/languages/javascript'
+   *
+   *   const lowlight = createLowlight({javascript})
+   *
+   *   console.log(lowlight.registered('funkyscript')) // => `false`
+   *
+   *   lowlight.registerAlias({javascript: 'funkyscript'})
+   *   console.log(lowlight.registered('funkyscript')) // => `true`
+   *   ```
    *
-   * @param {string} aliasOrLanguage
-   *   Name of a registered language or alias.
+   * @param {string} aliasOrName
+   *   Name of a language or alias for one.
    * @returns {boolean}
-   *   Whether `aliasOrlanguage` is registered.
+   *   Whether `aliasOrName` is registered.
    */
-  function registered(aliasOrLanguage) {
-    return Boolean(high.getLanguage(aliasOrLanguage))
+  function registered(aliasOrName) {
+    return Boolean(high.getLanguage(aliasOrName))
   }
 }
 

package.json

@@ -74,7 +74,6 @@
   "remarkConfig": {
     "plugins": [
       "remark-preset-wooorm",
-      "./script/count.js",
       "./script/support.js"
     ]
   },