Update docs

Author: wooorm

index.js

@@ -1,8 +1,14 @@
 /**
+ * Old export names, remove next major.
  * @typedef {import('./lib/core.js').RefractorRoot} RefractorRoot
  * @typedef {import('./lib/core.js').RefractorElement} RefractorElement
  * @typedef {import('./lib/core.js').Text} Text
+ *
+ * Old and new names:
  * @typedef {import('./lib/core.js').Grammar} Grammar
  * @typedef {import('./lib/core.js').Syntax} Syntax
+ *
+ * New names:
+ * @typedef {import('./lib/core.js').RefractorRoot} Root
  */
 export {refractor} from './lib/common.js'

lib/core.js

@@ -98,11 +98,55 @@ refractor.util.encode = encode
 // @ts-expect-error Overwrite Prism.
 refractor.Token.stringify = stringify
 
+/**
+ * Highlight `value` (code) as `language` (programming language).
+ *
+ * @param {string} value
+ *   Code to highlight.
+ * @param {string|Grammar} language
+ *   Programming language name, alias, or grammar.
+ * @returns {RefractorRoot}
+ *   Node representing highlighted code.
+ */
+function highlight(value, language) {
+  if (typeof value !== 'string') {
+    throw new TypeError('Expected `string` for `value`, got `' + value + '`')
+  }
+
+  /** @type {Grammar} */
+  let grammar
+  /** @type {string|undefined} */
+  let name
+
+  // `name` is a grammar object.
+  if (language && typeof language === 'object') {
+    grammar = language
+  } else {
+    name = language
+
+    if (typeof name !== 'string') {
+      throw new TypeError('Expected `string` for `name`, got `' + name + '`')
+    }
+
+    if (own.call(refractor.languages, name)) {
+      grammar = refractor.languages[name]
+    } else {
+      throw new Error('Unknown language: `' + name + '` is not registered')
+    }
+  }
+
+  return {
+    type: 'root',
+    children: Prism.highlight.call(refractor, value, grammar, name)
+  }
+}
+
 /**
  * Register a syntax.
- * Needed if you’re using `refractor/core.js`.
  *
  * @param {Syntax} syntax
+ *   Language function made for refractor, as in, the files in
+ *   `refractor/lang/*.js`.
  * @returns {void}
  */
 function register(syntax) {
@@ -120,23 +164,23 @@ function register(syntax) {
 }
 
 /**
- * Register a new `alias` for the `name` language.
+ * Register aliases for already registered languages.
  *
- * @param {Record<string, string|Array<string>>|string} name
+ * @param {Record<string, string|Array<string>>|string} language
  * @param {string|Array<string>} [alias]
  * @returns {void}
  */
-function alias(name, alias) {
+function alias(language, alias) {
   const languages = refractor.languages
   /** @type {Record<string, string|Array<string>>} */
   let map = {}
 
-  if (typeof name === 'string') {
+  if (typeof language === 'string') {
     if (alias) {
-      map[name] = alias
+      map[language] = alias
     }
   } else {
-    map = name
+    map = language
   }
 
   /** @type {string} */
@@ -156,60 +200,19 @@ function alias(name, alias) {
 }
 
 /**
- * Parse `value` according to the `language` (name or alias)
- * syntax.
+ * Check whether an `alias` or `language` is registered.
  *
- * @param {string} value
- * @param {string|Grammar} nameOrGrammar
- * @returns {RefractorRoot}
- */
-function highlight(value, nameOrGrammar) {
-  if (typeof value !== 'string') {
-    throw new TypeError('Expected `string` for `value`, got `' + value + '`')
-  }
-
-  /** @type {Grammar} */
-  let grammar
-  /** @type {string|undefined} */
-  let name
-
-  // `name` is a grammar object.
-  if (nameOrGrammar && typeof nameOrGrammar === 'object') {
-    grammar = nameOrGrammar
-  } else {
-    name = nameOrGrammar
-
-    if (typeof name !== 'string') {
-      throw new TypeError('Expected `string` for `name`, got `' + name + '`')
-    }
-
-    if (own.call(refractor.languages, name)) {
-      grammar = refractor.languages[name]
-    } else {
-      throw new Error('Unknown language: `' + name + '` is not registered')
-    }
-  }
-
-  return {
-    type: 'root',
-    children: Prism.highlight.call(refractor, value, grammar, name)
-  }
-}
-
-/**
- * Check if a `language` (name or alias) is registered.
- *
- * @param {string} language
+ * @param {string} aliasOrLanguage
  * @returns {boolean}
  */
-function registered(language) {
-  if (typeof language !== 'string') {
+function registered(aliasOrLanguage) {
+  if (typeof aliasOrLanguage !== 'string') {
     throw new TypeError(
-      'Expected `string` for `language`, got `' + language + '`'
+      'Expected `string` for `aliasOrLanguage`, got `' + aliasOrLanguage + '`'
     )
   }
 
-  return own.call(refractor.languages, language)
+  return own.call(refractor.languages, aliasOrLanguage)
 }
 
 /**