@vanillaes/jsdown 0.1.1

package/README.md

@@ -0,0 +1,41 @@
+<p align="center"><strong>✓  NOTICE: This project is currently a WIP  ✓</strong></p>
+
+<h1 align="center">JSDown</h1>
+
+<div align="center">📜  Markdown Doc Generator for JSDoc  📜</div>
+
+<br />
+
+<div align="center">
+  <a href="https://github.com/vanillaes/jsdown/releases"><img src="https://badgen.net/github/tag/vanillaes/jsdown?cache-control=no-cache" alt="GitHub Release"></a>
+  <a href="https://www.npmjs.com/package/@vanillaes/jsdown"><img src="https://badgen.net/npm/v/@vanillaes/jsdown?icon=npm" alt="NPM Version"></a>
+  <a href="https://www.npmjs.com/package/@vanillaes/jsdown"><img src="https://badgen.net/npm/dm/@vanillaes/jsdown?icon=npm" alt="NPM Downloads"></a>
+  <a href="https://github.com/vanillaes/jsdown/actions"><img src="https://github.com/vanillaes/jsdown/workflows/Latest/badge.svg" alt="Latest Status"></a>
+  <a href="https://github.com/vanillaes/jsdown/actions"><img src="https://github.com/vanillaes/jsdown/workflows/Release/badge.svg" alt="Release Status"></a>
+</div>
+
+## Features
+
+- **No Configuration**
+- Feed it JSDoc types and it spits out Markdown
+
+## jsdown
+
+### Arguments
+
+`jsdown [...options] [files...]`
+
+- `[files]` - File(s) to lint (default `**/!(*.spec|index).js`)
+
+### Usage
+
+```sh
+# generate documentation
+jsdown
+
+```sh
+# generate documentation (matching a different file(s))
+lint-es '**/!(*.spec|index).cjs'
+```
+
+*Note: In Linux/OSX, matcher patterns must be delimited in quotes.*

package/bin/jsdown.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { createDocs } from '../src/index.js'
+import { Command } from 'commander'
+
+import { createRequire } from 'node:module'
+const require = createRequire(import.meta.url)
+const pkg = require('../package.json')
+
+const program = new Command()
+  .name('jsdown')
+  .description('Markdown Doc Generator for JSDoc')
+  .version(pkg.version, '-v, --version')
+
+program
+  .description('Lint file(s) matching the provided pattern (default *.spec.js)')
+  .argument('[files]', 'file(s) to lint', '**/!(*.spec|index).js')
+  .action((files, options) => {
+    createDocs(files, options)
+  })
+
+program.parse(process.argv)

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@vanillaes/jsdown",
+  "version": "0.1.1",
+  "description": "Markdown Doc Generator for JSDoc",
+  "keywords": [
+    "ecmascript",
+    "esm",
+    "esmodules",
+    "cli",
+    "markdown",
+    "jsdoc",
+    "documentation"
+  ],
+  "repository": "https://github.com/vanillaes/jsdown",
+  "author": "Evan Plaice <evanplaice@gmail.com> (https://evanplaice.com)",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "jsdown": "bin/jsdown.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "esmtk test",
+    "lint": "esmtk lint",
+    "type": "esmtk type",
+    "typings": "esmtk typings",
+    "clean": "esmtk clean --typings",
+    "preview": "esmtk preview",
+    "preversion": "npm run test && npm run lint",
+    "postversion": "git push --follow-tags"
+  },
+  "dependencies": {
+    "@vanillaes/esmtk": "^1.8.0",
+    "commander": "^14.0.3",
+    "doctrine": "^3.0.0",
+    "lodash-es": "^4.18.1"
+  }
+}

package/src/alias.js

@@ -0,0 +1,231 @@
+/* eslint-disable jsdoc/check-tag-names */
+
+import _ from 'lodash-es'
+
+/**
+ * The Alias constructor.
+ * @constructor
+ * @param {string} name The alias name.
+ * @param {object} owner The alias owner.
+ */
+export function Alias (name, owner) {
+  this._owner = owner
+  this._name = name
+}
+
+/**
+ * Extracts the entry's `alias` objects.
+ * @memberOf Alias
+ * @param {number} [index] The index of the array value to return.
+ * @returns {Array|string} Returns the entry's `alias` objects.
+ */
+function getAliases (index) {
+  return index == null ? [] : undefined
+}
+
+/**
+ * Extracts the function call from the owner entry.
+ * @memberOf Alias
+ * @returns {string} Returns the function call.
+ */
+function getCall () {
+  return this._owner.getCall()
+}
+
+/**
+ * Extracts the owner entry's `category` data.
+ * @memberOf Alias
+ * @returns {string} Returns the owner entry's `category` data.
+ */
+function getCategory () {
+  return this._owner.getCategory()
+}
+
+/**
+ * Extracts the owner entry's description.
+ * @memberOf Alias
+ * @returns {string} Returns the owner entry's description.
+ */
+function getDesc () {
+  return this._owner.getDesc()
+}
+
+/**
+ * Extracts the owner entry's `example` data.
+ * @memberOf Alias
+ * @returns {string} Returns the owner entry's `example` data.
+ */
+function getExample () {
+  return this._owner.getExample()
+}
+
+/**
+ * Extracts the entry's hash value for permalinking.
+ * @memberOf Alias
+ * @param {string} [style] The hash style.
+ * @returns {string} Returns the entry's hash value (without a hash itself).
+ */
+function getHash (style) {
+  return this._owner.getHash(style)
+}
+
+/**
+ * Resolves the owner entry's line number.
+ * @memberOf Alias
+ * @returns {number} Returns the owner entry's line number.
+ */
+function getLineNumber () {
+  return this._owner.getLineNumber()
+}
+
+/**
+ * Extracts the owner entry's `member` data.
+ * @memberOf Alias
+ * @param {number} [index] The index of the array value to return.
+ * @returns {Array|string} Returns the owner entry's `member` data.
+ */
+function getMembers (index) {
+  return this._owner.getMembers(index)
+}
+
+/**
+ * Extracts the owner entry's `name` data.
+ * @memberOf Alias
+ * @returns {string} Returns the owner entry's `name` data.
+ */
+function getName () {
+  return this._name
+}
+
+/**
+ * Gets the owner entry object.
+ * @memberOf Alias
+ * @returns {object} Returns the owner entry.
+ */
+function getOwner () {
+  return this._owner
+}
+
+/**
+ * Extracts the owner entry's `param` data.
+ * @memberOf Alias
+ * @param {number} [index] The index of the array value to return.
+ * @returns {Array} Returns the owner entry's `param` data.
+ */
+function getParams (index) {
+  return this._owner.getParams(index)
+}
+
+/**
+ * Extracts the owner entry's `returns` data.
+ * @memberOf Alias
+ * @returns {string} Returns the owner entry's `returns` data.
+ */
+function getReturns () {
+  return this._owner.getReturns()
+}
+
+/**
+ * Extracts the owner entry's `since` data.
+ * @memberOf Alias
+ * @returns {string} Returns the owner entry's `since` data.
+ */
+function getSince () {
+  return this._owner.getSince()
+}
+
+/**
+ * Extracts the owner entry's `type` data.
+ * @memberOf Alias
+ * @returns {string} Returns the owner entry's `type` data.
+ */
+function getType () {
+  return this._owner.getType()
+}
+
+/**
+ * Checks if the entry is an alias.
+ * @memberOf Alias
+ * @returns {boolean} Returns `true`.
+ */
+function isAlias () {
+  return true
+}
+
+/**
+ * Checks if the owner entry is a constructor.
+ * @memberOf Alias
+ * @returns {boolean} Returns `true` if a constructor, else `false`.
+ */
+function isCtor () {
+  return this._owner.isCtor()
+}
+
+/**
+ * Checks if the entry is a function reference.
+ * @memberOf Alias
+ * @returns {boolean} Returns `true` if the entry is a function reference, else `false`.
+ */
+function isFunction () {
+  return this._owner.isFunction()
+}
+
+/**
+ * Checks if the owner entry is a license.
+ * @memberOf Alias
+ * @returns {boolean} Returns `true` if a license, else `false`.
+ */
+function isLicense () {
+  return this._owner.isLicense()
+}
+
+/**
+ * Checks if the owner entry *is* assigned to a prototype.
+ * @memberOf Alias
+ * @returns {boolean} Returns `true` if assigned to a prototype, else `false`.
+ */
+function isPlugin () {
+  return this._owner.isPlugin()
+}
+
+/**
+ * Checks if the owner entry is private.
+ * @memberOf Alias
+ * @returns {boolean} Returns `true` if private, else `false`.
+ */
+function isPrivate () {
+  return this._owner.isPrivate()
+}
+
+/**
+ * Checks if the owner entry is *not* assigned to a prototype.
+ * @memberOf Alias
+ * @returns {boolean} Returns `true` if not assigned to a prototype, else `false`.
+ */
+function isStatic () {
+  return this._owner.isStatic()
+}
+
+_.assign(Alias.prototype, {
+  getAliases,
+  getCall,
+  getCategory,
+  getDesc,
+  getExample,
+  getHash,
+  getLineNumber,
+  getMembers,
+  getName,
+  getOwner,
+  getParams,
+  getReturns,
+  getSince,
+  getType,
+  isAlias,
+  isCtor,
+  isFunction,
+  isLicense,
+  isPlugin,
+  isPrivate,
+  isStatic
+})

package/src/docdown.js

@@ -0,0 +1,31 @@
+import { generateDoc } from './index.js'
+import { readFileSync } from 'node:fs'
+import { basename } from 'node:path'
+import _ from 'lodash-es'
+
+/**
+ * Generates Markdown documentation based on JSDoc comments.
+ * @param {object} options The options object.
+ * @param {string} options.path The input file path.
+ * @param {string} options.url The source URL.
+ * @param {string} [options.lang] The language indicator for code blocks (default: `js`).
+ * @param {boolean} [options.sort] Specify whether entries are sorted (default: `true`).
+ * @param {string} [options.style] The hash style for links ('default' or 'github').
+ * @param {string} [options.title] The documentation title (default: `${path} API documentation`).
+ * @param {string} [options.toc] The table of contents organization style ('categories' or 'properties').
+ * @returns {string} The generated Markdown code.
+ */
+export function docdown (options) {
+  options = _.defaults(options, {
+    lang: 'js',
+    sort: true,
+    style: 'default',
+    title: basename(options.path) + ' API documentation',
+    toc: 'properties'
+  })
+
+  if (!options.path || !options.url) {
+    throw new Error('Path and URL must be specified')
+  }
+  return generateDoc(readFileSync(options.path, 'utf8'), options)
+}

package/src/entry.js

@@ -0,0 +1,532 @@
+/* eslint-disable jsdoc/check-tag-names,jsdoc/reject-function-type,@stylistic/multiline-ternary */
+
+import { Alias, compareNatural, format, parse } from './index.js'
+import _ from 'lodash-es'
+
+/**
+ * Gets the param type of `tag`.
+ * @private
+ * @param {object} tag The param tag to inspect.
+ * @returns {string} Returns the param type.
+ */
+export function getParamType (tag) {
+  let expression = tag.expression
+  let result = ''
+  const type = tag.type
+
+  switch (type) {
+    case 'AllLiteral':
+      result = '*'
+      break
+
+    case 'NameExpression':
+      result = _.toString(tag.name)
+      break
+
+    case 'RestType':
+      result = '...' + result
+      break
+
+    case 'TypeApplication':
+      expression = undefined
+      result = _(tag)
+        .chain()
+        .get('applications')
+        .map(_.flow(getParamType, _.add))
+        .sort(compareNatural)
+        .join('|')
+        .value()
+      break
+
+    case 'UnionType':
+      result = _(tag)
+        .chain()
+        .get('elements')
+        .map(getParamType)
+        .sort(compareNatural)
+        .join('|')
+        .value()
+  }
+  if (expression) {
+    result += getParamType(expression)
+  }
+  return type === 'UnionType'
+    ? ('(' + result + ')')
+    : result
+}
+
+/**
+ * Gets an `entry` tag by `tagName`.
+ * @private
+ * @param {object} entry The entry to inspect.
+ * @param {string} tagName The name of the tag.
+ * @returns {object | null} Returns the tag.
+ */
+function getTag (entry, tagName) {
+  const parsed = entry.parsed
+  return _.find(parsed.tags, ['title', tagName]) || null
+}
+
+/**
+ * Gets an `entry` tag value by `tagName`.
+ * @private
+ * @param {object} entry The entry to inspect.
+ * @param {string} tagName The name of the tag.
+ * @returns {string} Returns the tag value.
+ */
+function getValue (entry, tagName) {
+  const parsed = entry.parsed
+  let result = parsed.description
+  const tag = getTag(entry, tagName)
+
+  if (tagName === 'alias') {
+    result = _.get(tag, 'name')
+
+    // Doctrine can't parse alias tags containing multiple values so extract
+    // them from the error message.
+    const error = _.first(_.get(tag, 'errors'))
+    if (error) {
+      result += error.replace(/^[^']*'|'[^']*$/g, '')
+    }
+  } else if (tagName === 'type') {
+    result = _.get(tag, 'type.name')
+  } else if (tagName !== 'description') {
+    result = _.get(tag, 'name') || _.get(tag, 'description')
+  }
+  return tagName === 'example'
+    ? _.toString(result)
+    : format(result)
+}
+
+/**
+ * Checks if `entry` has a tag of `tagName`.
+ * @private
+ * @param {object} entry The entry to inspect.
+ * @param {string} tagName The name of the tag.
+ * @returns {boolean} Returns `true` if the tag is found, else `false`.
+ */
+function hasTag (entry, tagName) {
+  return getTag(entry, tagName) !== null
+}
+
+/**
+ * Converts CR+LF line endings to LF.
+ * @private
+ * @param {string} string The string to convert.
+ * @returns {string} Returns the converted string.
+ */
+function normalizeEOL (string) {
+  return string.replace(/\r\n/g, '\n')
+}
+
+/**
+ * The Entry constructor.
+ * @constructor
+ * @param {string} entry The documentation entry to analyse.
+ * @param {string} source The source code.
+ * @param {string} [lang] The language highlighter used for code examples (default: 'js').
+ */
+export function Entry (entry, source, lang) {
+  entry = normalizeEOL(entry)
+
+  this.entry = entry
+  this.lang = lang == null ? 'js' : lang
+  this.parsed = parse(entry.replace(/(\*)\/\s*.+$/, '*'))
+  this.source = normalizeEOL(source)
+  this.getCall = _.memoize(this.getCall)
+  this.getCategory = _.memoize(this.getCategory)
+  this.getDesc = _.memoize(this.getDesc)
+  this.getExample = _.memoize(this.getExample)
+  this.getHash = _.memoize(this.getHash)
+  this.getLineNumber = _.memoize(this.getLineNumber)
+  this.getName = _.memoize(this.getName)
+  this.getRelated = _.memoize(this.getRelated)
+  this.getReturns = _.memoize(this.getReturns)
+  this.getSince = _.memoize(this.getSince)
+  this.getType = _.memoize(this.getType)
+  this.isAlias = _.memoize(this.isAlias)
+  this.isCtor = _.memoize(this.isCtor)
+  this.isFunction = _.memoize(this.isFunction)
+  this.isLicense = _.memoize(this.isLicense)
+  this.isPlugin = _.memoize(this.isPlugin)
+  this.isPrivate = _.memoize(this.isPrivate)
+  this.isStatic = _.memoize(this.isStatic)
+  this._aliases = this._members = this._params = undefined
+}
+
+/**
+ * Extracts the documentation entries from source code.
+ * @static
+ * @memberOf Entry
+ * @param {string} source The source code.
+ * @returns {Array} Returns the array of entries.
+ */
+export function getEntries (source) {
+  return _.toString(source).match(/\/\*\*(?![-!])[\s\S]*?\*\/\s*.+/g) || []
+}
+
+/**
+ * Extracts the entry's `alias` objects.
+ * @memberOf Entry
+ * @param {number} index The index of the array value to return.
+ * @returns {Array|string} Returns the entry's `alias` objects.
+ */
+function getAliases (index) {
+  if (this._aliases === undefined) {
+    const owner = this
+    this._aliases = _(getValue(this, 'alias'))
+      .split(/,\s*/)
+      .compact()
+      .sort(compareNatural)
+      .map(function (value) { return new Alias(value, owner) })
+      .value()
+  }
+  const result = this._aliases
+  return index === undefined ? result : result[index]
+}
+
+/**
+ * Extracts the function call from the entry.
+ * @memberOf Entry
+ * @returns {string} Returns the function call.
+ */
+function getCall () {
+  let result = _.trim(_.get(/\*\/\s*(?:function\s+)?([^\s(]+)\s*\(/.exec(this.entry), 1))
+  if (!result) {
+    result = _.trim(_.get(/\*\/\s*(.*?)[:=,]/.exec(this.entry), 1))
+    result = /['"]$/.test(result)
+      ? _.trim(result, '"\'')
+      : result.split('.').pop().split(/^(?:const|let|var) /).pop()
+  }
+  const name = getValue(this, 'name') || result
+  if (!this.isFunction()) {
+    return name
+  }
+  const params = this.getParams()
+  result = _.castArray(result)
+
+  // Compile the function call syntax.
+  _.each(params, function (param) {
+    const paramValue = param[1]
+    const parentParam = _.get(/\w+(?=\.[\w.]+)/.exec(paramValue), 0)
+
+    const parentIndex = parentParam == null ? -1 : _.findIndex(params, function (param) {
+      return _.trim(param[1], '[]').split(/\s*=/)[0] === parentParam
+    })
+
+    // Skip params that are properties of other params (e.g. `options.leading`).
+    if (_.get(params[parentIndex], 0) !== 'Object') {
+      result.push(paramValue)
+    }
+  })
+
+  // Format the function call.
+  return name + '(' + result.slice(1).join(', ') + ')'
+}
+
+/**
+ * Extracts the entry's `category` data.
+ * @memberOf Entry
+ * @returns {string} Returns the entry's `category` data.
+ */
+function getCategory () {
+  const result = getValue(this, 'category')
+  return result || (this.getType() === 'Function' ? 'Methods' : 'Properties')
+}
+
+/**
+ * Extracts the entry's description.
+ * @memberOf Entry
+ * @returns {string} Returns the entry's description.
+ */
+function getDesc () {
+  const type = this.getType()
+  const result = getValue(this, 'description')
+
+  return (!result || type === 'Function' || type === 'unknown')
+    ? result
+    : ('(' + _.trim(type.replace(/\|/g, ', '), '()') + '): ' + result)
+}
+
+/**
+ * Extracts the entry's `example` data.
+ * @memberOf Entry
+ * @returns {string} Returns the entry's `example` data.
+ */
+function getExample () {
+  const result = getValue(this, 'example')
+  return result && ('```' + this.lang + '\n' + result + '\n```')
+}
+
+/**
+ * Extracts the entry's hash value for permalinking.
+ * @memberOf Entry
+ * @param {string} [style] The hash style.
+ * @returns {string} Returns the entry's hash value (without a hash itself).
+ */
+function getHash (style) {
+  let result = _.toString(this.getMembers(0))
+  if (style === 'github') {
+    if (result) {
+      result += this.isPlugin() ? 'prototype' : ''
+    }
+    result += this.getCall()
+    return result
+      .replace(/[\\.=|'"(){}[\]\t ]/g, '')
+      .replace(/[#,]+/g, '-')
+      .toLowerCase()
+  }
+  if (result) {
+    result += '-' + (this.isPlugin() ? 'prototype-' : '')
+  }
+  result += this.isAlias() ? this.getOwner().getName() : this.getName()
+  return result
+    .replace(/\./g, '-')
+    .replace(/^_-/, '')
+}
+
+/**
+ * Resolves the entry's line number.
+ * @memberOf Entry
+ * @returns {number} Returns the entry's line number.
+ */
+function getLineNumber () {
+  const lines = this.source
+    .slice(0, this.source.indexOf(this.entry) + this.entry.length)
+    .match(/\n/g)
+    .slice(1)
+
+  // Offset by 2 because the first line number is before a line break and the
+  // last line doesn't include a line break.
+  return lines.length + 2
+}
+
+/**
+ * Extracts the entry's `member` data.
+ * @memberOf Entry
+ * @param {number} [index] The index of the array value to return.
+ * @returns {Array|string} Returns the entry's `member` data.
+ */
+function getMembers (index) {
+  if (this._members === undefined) {
+    this._members = _(getValue(this, 'member') || getValue(this, 'memberOf'))
+      .split(/,\s*/)
+      .compact()
+      .sort(compareNatural)
+      .value()
+  }
+  const result = this._members
+  return index === undefined ? result : result[index]
+}
+
+/**
+ * Extracts the entry's `name` data.
+ * @memberOf Entry
+ * @returns {string} Returns the entry's `name` data.
+ */
+function getName () {
+  return hasTag(this, 'name')
+    ? getValue(this, 'name')
+    : _.toString(_.first(this.getCall().split('(')))
+}
+
+/**
+ * Extracts the entry's `param` data.
+ * @memberOf Entry
+ * @param {number} [index] The index of the array value to return.
+ * @returns {Array} Returns the entry's `param` data.
+ */
+function getParams (index) {
+  if (this._params === undefined) {
+    this._params = _(this.parsed.tags)
+      .filter(['title', 'param'])
+      .filter('name')
+      .map(function (tag) {
+        const defaultValue = tag['default']
+        const desc = format(tag.description)
+        let name = _.toString(tag.name)
+        const type = getParamType(tag.type)
+
+        if (defaultValue != null) {
+          name += '=' + defaultValue
+        }
+        if (_.get(tag, 'type.type') === 'OptionalType') {
+          name = '[' + name + ']'
+        }
+        return [type, name, desc]
+      })
+      .value()
+  }
+  const result = this._params
+  return index === undefined ? result : result[index]
+}
+
+/**
+ * Extracts the entry's `see` data.
+ * @memberOf Entry
+ * @returns {Array} Returns the entry's `see` data as links.
+ */
+function getRelated () {
+  const relatedValues = getValue(this, 'see')
+  if (relatedValues && relatedValues.trim().length > 0) {
+    const relatedItems = relatedValues.split(',').map((relatedItem) => relatedItem.trim())
+    return relatedItems.map((relatedItem) => '[' + relatedItem + '](#' + relatedItem + ')')
+  } else {
+    return []
+  }
+}
+
+/**
+ * Extracts the entry's `returns` data.
+ * @memberOf Entry
+ * @returns {Array} Returns the entry's `returns` data.
+ */
+function getReturns () {
+  const tag = getTag(this, 'returns')
+  const desc = _.toString(_.get(tag, 'description'))
+  const type = _.toString(_.get(tag, 'type.name')) || '*'
+
+  return tag ? [type, desc] : []
+}
+
+/**
+ * Extracts the entry's `since` data.
+ * @memberOf Entry
+ * @returns {string} Returns the entry's `since` data.
+ */
+function getSince () {
+  return getValue(this, 'since')
+}
+
+/**
+ * Extracts the entry's `type` data.
+ * @memberOf Entry
+ * @returns {string} Returns the entry's `type` data.
+ */
+function getType () {
+  const result = getValue(this, 'type')
+  if (!result) {
+    return this.isFunction() ? 'Function' : 'unknown'
+  }
+  return /^(?:array|function|object|regexp)$/.test(result)
+    ? _.capitalize(result)
+    : result
+}
+
+/**
+ * Checks if the entry is an alias.
+ * @memberOf Entry
+ * @type {Function}
+ * @returns {boolean} Returns `false`.
+ */
+const isAlias = _.constant(false)
+
+/**
+ * Checks if the entry is a constructor.
+ * @memberOf Entry
+ * @returns {boolean} Returns `true` if a constructor, else `false`.
+ */
+function isCtor () {
+  return hasTag(this, 'constructor')
+}
+
+/**
+ * Checks if the entry is a function reference.
+ * @memberOf Entry
+ * @returns {boolean} Returns `true` if the entry is a function reference, else `false`.
+ */
+function isFunction () {
+  return !!(
+    this.isCtor() ||
+    _.size(this.getParams()) ||
+    _.size(this.getReturns()) ||
+    hasTag(this, 'function') ||
+    /\*\/\s*(?:function\s+)?[^\s(]+\s*\(/.test(this.entry)
+  )
+}
+
+/**
+ * Checks if the entry is a license.
+ * @memberOf Entry
+ * @returns {boolean} Returns `true` if a license, else `false`.
+ */
+function isLicense () {
+  return hasTag(this, 'license')
+}
+
+/**
+ * Checks if the entry *is* assigned to a prototype.
+ * @memberOf Entry
+ * @returns {boolean} Returns `true` if assigned to a prototype, else `false`.
+ */
+function isPlugin () {
+  return (
+    !this.isCtor() &&
+    !this.isPrivate() &&
+    !this.isStatic()
+  )
+}
+
+/**
+ * Checks if the entry is private.
+ * @memberOf Entry
+ * @returns {boolean} Returns `true` if private, else `false`.
+ */
+function isPrivate () {
+  return (
+    this.isLicense() ||
+    hasTag(this, 'private') ||
+    _.isEmpty(this.parsed.tags)
+  )
+}
+
+/**
+ * Checks if the entry is *not* assigned to a prototype.
+ * @memberOf Entry
+ * @returns {boolean} Returns `true` if not assigned to a prototype, else `false`.
+ */
+function isStatic () {
+  const isPublic = !this.isPrivate()
+  let result = isPublic && hasTag(this, 'static')
+
+  // Get the result in cases where it isn't explicitly stated.
+  if (isPublic && !result) {
+    const parent = _.last(_.toString(this.getMembers(0)).split(/[#.]/))
+    if (!parent) {
+      return true
+    }
+    const source = this.source
+    _.each(getEntries(source), function (entry) {
+      entry = new Entry(entry, source)
+      if (entry.getName() === parent) {
+        result = !entry.isCtor()
+        return false
+      }
+    })
+  }
+  return result
+}
+
+_.assign(Entry.prototype, {
+  getAliases,
+  getCall,
+  getCategory,
+  getDesc,
+  getExample,
+  getHash,
+  getLineNumber,
+  getMembers,
+  getName,
+  getParams,
+  getRelated,
+  getReturns,
+  getSince,
+  getType,
+  isAlias,
+  isCtor,
+  isFunction,
+  isLicense,
+  isPlugin,
+  isPrivate,
+  isStatic
+})

package/src/generator.js

@@ -0,0 +1,369 @@
+/* eslint-disable no-template-curly-in-string */
+
+import { Entry, compareNatural, getEntries, format } from './index.js'
+import _ from 'lodash-es'
+
+const push = Array.prototype.push
+const specialCategories = ['Methods', 'Properties']
+const token = '@@token@@'
+
+const reCode = /`.*?`/g
+const reToken = /@@token@@/g
+const reSpecialCategory = RegExp('^(?:' + specialCategories.join('|') + ')$')
+
+const htmlEscapes = {
+  '*': '*',
+  '[': '[',
+  ']': ']'
+}
+
+/**
+ * Escape special Markdown characters in a string.
+ * @private
+ * @param {string} string The string to escape.
+ * @returns {string} Returns the escaped string.
+ */
+function escape (string) {
+  const snippets = []
+
+  // Replace all code snippets with a token.
+  string = string.replace(reCode, function (match) {
+    snippets.push(match)
+    return token
+  })
+
+  _.forOwn(htmlEscapes, function (replacement, chr) {
+    string = string.replace(RegExp('(\\\\?)\\' + chr, 'g'), function (match, backslash) {
+      return backslash ? match : replacement
+    })
+  })
+
+  // Replace all tokens with code snippets.
+  return string.replace(reToken, function (match) {
+    return snippets.shift()
+  })
+}
+
+/**
+ * Get the seperator (`.` or `.prototype.`)
+ * @private
+ * @param {Entry} entry object to get selector for.
+ * @returns {string} Returns the member seperator.
+ */
+function getSeparator (entry) {
+  return entry.isPlugin() ? '.prototype.' : '.'
+}
+
+/**
+ * Modify a string by replacing named tokens with matching associated object values.
+ * @private
+ * @param {string} string The string to modify.
+ * @param {object} data The template data object.
+ * @returns {string} Returns the modified string.
+ */
+function interpolate (string, data) {
+  return format(_.template(string)(data))
+}
+
+/**
+ * Make an anchor link.
+ * @private
+ * @param {string} href The anchor href.
+ * @param {string} text The anchor text.
+ * @returns {string} Returns the anchor HTML.
+ */
+function makeAnchor (href, text) {
+  return '<a href="' + href + '">' + _.toString(text) + '</a>'
+}
+
+/* ---------------------------------------------------------------------------- */
+
+/**
+ * Generates the documentation from JS source.
+ * @param {string} source source code to generate the documentation for.
+ * @param {object} options options object.
+ * @returns {string} Returns the documentation markdown.
+ */
+export function generateDoc (source, options) {
+  const api = []
+  const noTOC = options.toc === 'none'
+  const byCategories = options.toc === 'categories'
+  const entries = getEntries(source)
+  const organized = Object.create(null)
+  const sortEntries = options.sort
+  const style = options.style
+  const url = options.url
+
+  // Add entries and aliases to the API list.
+  _.each(entries, function (entry) {
+    entry = new Entry(entry, source)
+    api.push(entry)
+
+    const aliases = entry.getAliases()
+    if (!_.isEmpty(aliases)) {
+      push.apply(api, aliases)
+    }
+  })
+
+  // Build the list of categories for the TOC and generate content for each entry.
+  _.each(api, function (entry) {
+    // Exit early if the entry is private or has no name.
+    const name = entry.getName()
+    if (!name || entry.isPrivate()) {
+      return
+    }
+    let tocGroup
+    const member = entry.getMembers(0) || ''
+    const separator = member ? getSeparator(entry) : ''
+
+    // Add the entry to the TOC.
+    if (byCategories) {
+      const category = entry.getCategory()
+      tocGroup = organized[category] || (organized[category] = [])
+    } else {
+      let memberGroup
+      if (!member ||
+          entry.isCtor() ||
+          (entry.getType() === 'Object' &&
+            !/[=:]\s*(?:null|undefined)\s*[,;]?$/gi.test(entry.entry))
+      ) {
+        memberGroup = (member ? member + getSeparator(entry) : '') + name
+      } else if (entry.isStatic()) {
+        memberGroup = member
+      } else if (!entry.isCtor()) {
+        memberGroup = member + getSeparator(entry).slice(0, -1)
+      }
+      tocGroup = organized[memberGroup] || (organized[memberGroup] = [])
+    }
+    tocGroup.push(entry)
+
+    // Skip aliases.
+    if (entry.isAlias()) {
+      return
+    }
+    // Start markdown for the entry.
+    const entryMarkdown = ['\n<!-- div -->\n']
+
+    const entryData = {
+      call: entry.getCall(),
+      category: entry.getCategory(),
+      entryHref: '#${hash}',
+      entryLink: _.get(options, 'entryLink', style === 'github' ? '' : '<a href="${entryHref}">#</a>&nbsp;'),
+      hash: entry.getHash(style),
+      member,
+      name,
+      separator,
+      sourceHref: url + '#L' + entry.getLineNumber(),
+      sourceLink: _.get(options, 'sourceLink', '[&#x24C8;](${sourceHref} "View in source")'),
+      tocHref: '1',
+      tocLink: _.get(options, 'tocLink', '[&#x24C9;][${tocHref}]')
+    }
+
+    _.each([
+      'entryHref', 'sourceHref', 'tocHref',
+      'entryLink', 'sourceLink', 'tocLink'
+    ], function (option) {
+      entryData[option] = interpolate(entryData[option], entryData)
+    })
+
+    // Add the heading.
+    entryMarkdown.push(interpolate(
+      '<h3 id="${hash}">${entryLink}<code>${member}${separator}${call}</code></h3>\n' +
+      interpolate(
+        _([
+          '${sourceLink}',
+          _.get(options, 'sublinks', []),
+          '${tocLink}'
+        ])
+          .flatten()
+          .compact()
+          .join(' '),
+        entryData
+      )
+        .replace(/ {2,}/g, ' '),
+      entryData
+    ))
+
+    // Add the description.
+    entryMarkdown.push('\n' + entry.getDesc() + '\n')
+
+    // Add optional related.
+    const relatedItems = entry.getRelated()
+    if (!_.isEmpty(relatedItems)) {
+      entryMarkdown.push(
+        '#### Related',
+        relatedItems.join(', '),
+        ''
+      )
+    }
+    // Add optional since version.
+    const since = entry.getSince()
+    if (!_.isEmpty(since)) {
+      entryMarkdown.push(
+        '#### Since',
+        since,
+        ''
+      )
+    }
+    // Add optional aliases.
+    const aliases = entry.getAliases()
+    if (!_.isEmpty(aliases)) {
+      entryMarkdown.push(
+        '#### Aliases',
+        '*' +
+        _.map(aliases, function (alias) {
+          return `${member}${separator}${alias.getName()}`
+        }).join(', ') +
+        '*',
+        ''
+      )
+    }
+    // Add optional function parameters.
+    const params = entry.getParams()
+    if (!_.isEmpty(params)) {
+      entryMarkdown.push('#### Arguments')
+      _.each(params, function (param, index) {
+        let paramType = param[0]
+        if (_.startsWith(paramType, '(')) {
+          paramType = _.trim(paramType, '()')
+        }
+        const entryValues = {
+          desc: escape(param[2]),
+          name: param[1],
+          num: index + 1,
+          type: escape(paramType)
+        }
+        entryMarkdown.push(`${entryValues.num}. ${entryValues.name} (${entryValues.type}): ${entryValues.desc}`)
+      })
+      entryMarkdown.push('')
+    }
+    // Add optional functions returns.
+    const returns = entry.getReturns()
+    if (!_.isEmpty(returns)) {
+      let returnType = returns[0]
+      if (_.startsWith(returnType, '(')) {
+        returnType = _.trim(returnType, '()')
+      }
+      const entryValues = {
+        desc: escape(returns[1]),
+        type: escape(returnType)
+      }
+      entryMarkdown.push(
+        '#### Returns',
+        `(${entryValues.type}): ${entryValues.desc}`,
+        ''
+      )
+    }
+    // Add optional function example.
+    const example = entry.getExample()
+    if (example) {
+      entryMarkdown.push('#### Example', example)
+    }
+    // End markdown for the entry.
+    entryMarkdown.push('---\n\n<!-- /div -->')
+
+    entry.markdown = entryMarkdown.join('\n')
+  })
+
+  // Add TOC headers.
+  const tocGroups = _.keys(organized)
+  if (byCategories) {
+    // Remove special categories before sorting.
+    const catogoriesUsed = _.intersection(tocGroups, specialCategories)
+    _.pullAll(tocGroups, catogoriesUsed)
+
+    // Sort categories and add special categories back.
+    if (sortEntries) {
+      tocGroups.sort(compareNatural)
+    }
+    push.apply(tocGroups, catogoriesUsed)
+  } else {
+    tocGroups.sort(compareNatural)
+  }
+
+  let tocMarkdown = []
+  if (!noTOC) {
+    // Start markdown for TOC categories.
+    tocMarkdown = ['<!-- div class="toc-container" -->\n']
+    _.each(tocGroups, function (group) {
+      tocMarkdown.push(
+        '<!-- div -->\n',
+        '## `' + group + '`'
+      )
+
+      if (sortEntries && organized[group]) {
+        // Sort the TOC groups.
+        organized[group].sort(function (value, other) {
+          const valMember = value.getMembers(0)
+          const othMember = other.getMembers(0)
+
+          return compareNatural(
+            (valMember ? (valMember + getSeparator(value)) : '') + value.getName(),
+            (othMember ? (othMember + getSeparator(other)) : '') + other.getName()
+          )
+        })
+      }
+      // Add TOC entries for each category.
+      _.each(organized[group], function (entry) {
+        const member = entry.getMembers(0) || ''
+        const name = entry.getName()
+        const sep = getSeparator(entry)
+        const title = escape((member ? (member + sep) : '') + name)
+
+        if (entry.isAlias()) {
+          // An alias has a more complex html structure.
+          const owner = entry.getOwner()
+          tocMarkdown.push(
+            '* <a href="#' + owner.getHash(style) + '" class="alias">`' +
+            title + '` -> `' + owner.getName() + '`' +
+            '</a>'
+          )
+        } else {
+          // Add a simple TOC entry.
+          tocMarkdown.push(
+            '* ' +
+            makeAnchor(
+              '#' + entry.getHash(style),
+              '`' + title + '`'
+            )
+          )
+        }
+      })
+      tocMarkdown.push('\n<!-- /div -->\n')
+    })
+
+    // End markdown for the TOC.
+    tocMarkdown.push('<!-- /div -->\n')
+  }
+
+  const docMarkdown = ['# ' + options.title + '\n']
+  push.apply(docMarkdown, tocMarkdown)
+  docMarkdown.push('<!-- div class="doc-container" -->\n')
+
+  _.each(tocGroups, function (group) {
+    docMarkdown.push('<!-- div -->\n')
+    let groupName = ''
+    if (byCategories && !reSpecialCategory.test(group)) {
+      groupName = '“' + group + '” Methods'
+    }
+    if (!noTOC) {
+      docMarkdown.push('## `' + (groupName || group) + '`')
+    }
+
+    _.each(organized[group], function (entry) {
+      if (entry.markdown) {
+        docMarkdown.push(entry.markdown)
+      }
+    })
+    docMarkdown.push('\n<!-- /div -->\n')
+  })
+
+  docMarkdown.push('<!-- /div -->\n')
+
+  // Add link back to the top of the TOC.
+  const tocHref = _.get(options, 'tocHref', '#' + _.get(tocGroups, 0, '').toLowerCase())
+  if (tocHref) {
+    docMarkdown.push(' [1]: ' + tocHref + ' "Jump back to the TOC."\n')
+  }
+  return docMarkdown.join('\n')
+}

package/src/index.js

@@ -0,0 +1,6 @@
+export { Alias } from './alias.js'
+export { docdown } from './docdown.js'
+export { Entry, getEntries } from './entry.js'
+export { generateDoc } from './generator.js'
+export { createDocs } from './jsdown.js'
+export { compareNatural, format, parse } from './util.js'

package/src/jsdown.js

@@ -0,0 +1,55 @@
+import { docdown } from './index.js'
+import { fileExists, match } from '@vanillaes/esmtk'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
+
+/**
+ * Create markdown documents for the JS + JSDoc sources
+ * @param {string} files the pattern(s) of file(s) to include
+ * @param {object} options 'jsdown' options
+ */
+export async function createDocs (files, options = {}) {
+  const sources = await match(files)
+  sources.forEach(file => createDoc(file))
+}
+
+/**
+ * Create a markdown document for a JS + JSDoc source
+ * @private
+ * @param {string} path path to JS source
+ */
+async function createDoc (path) {
+  // extract names
+  const dir = dirname(path)
+  const file = basename(path)
+  const name = basename(path, '.js')
+  const mdName = `${name}.md`
+
+  const srcPath = join(process.cwd(), 'src') // TODO: make this configurable?
+  const docPath = join(process.cwd(), 'docs') // TODO: make this configurable?
+
+  const exists = await !fileExists(docPath)
+  if (!exists) {
+    await mkdir(docPath, { recursive: true })
+  }
+
+  // build the docdown config
+  const config = {
+    title: `${dir}.${name}`,
+    toc: 'none',
+    tocHref: '',
+    tocLink: '',
+    path: join(srcPath, file),
+    sourceLink: '',
+    style: 'github',
+    url: 'https://github.com/vanillaes/absurdum/doc/README.md' // TODO: look up project name
+  }
+
+  // create the markdown file
+  const markdown = docdown(config)
+  await writeFile(join(docPath, mdName), markdown, { flag: 'w+' }, (err) => {
+    if (err) {
+      throw Error(err)
+    }
+  })
+}

package/src/util.js

@@ -0,0 +1,85 @@
+/* eslint-disable jsdoc/check-tag-names,jsdoc/reject-any-type */
+
+import doctrine from 'doctrine'
+import _ from 'lodash-es'
+
+const reCode = /`.*?`/g
+const reToken = /@@token@@/g
+const split = String.prototype.split
+const token = '@@token@@'
+
+/**
+ * The `Array#sort` comparator to produce a
+ * [natural sort order](https://en.wikipedia.org/wiki/Natural_sort_order).
+ * @memberOf util
+ * @param {*} value The value to compare.
+ * @param {*} other The other value to compare.
+ * @returns {number} Returns the sort order indicator for `value`.
+ */
+export function compareNatural (value, other) {
+  let index = -1
+  const valParts = split.call(value, '.')
+  const valLength = valParts.length
+  const othParts = split.call(other, '.')
+  const othLength = othParts.length
+  const length = Math.min(valLength, othLength)
+
+  while (++index < length) {
+    const valPart = valParts[index]
+    const othPart = othParts[index]
+
+    if (valPart > othPart && othPart !== 'prototype') {
+      return 1
+    } else if (valPart < othPart && valPart !== 'prototype') {
+      return -1
+    }
+  }
+  return valLength > othLength ? 1 : (valLength < othLength ? -1 : 0)
+}
+
+/**
+ * Performs common string formatting operations.
+ * @memberOf util
+ * @param {string} string The string to format.
+ * @returns {string} Returns the formatted string.
+ */
+export function format (string) {
+  string = _.toString(string)
+
+  // Replace all code snippets with a token.
+  const snippets = []
+  string = string.replace(reCode, function (match) {
+    snippets.push(match)
+    return token
+  })
+
+  return string
+    // Add line breaks.
+    .replace(/:\n(?=[\t ]*\S)/g, ':<br>\n')
+    .replace(/\n( *)[-*](?=[\t ]+\S)/g, '\n<br>\n$1*')
+    .replace(/^[\t ]*\n/gm, '<br>\n<br>\n')
+    // Normalize whitespace.
+    .replace(/\n +/g, ' ')
+    // Italicize parentheses.
+    .replace(/(^|\s)(\(.+\))/g, '$1*$2*')
+    // Mark numbers as inline code.
+    .replace(/[\t ](-?\d+(?:.\d+)?)(?!\.[^\n])/g, ' `$1`')
+    // Replace all tokens with code snippets.
+    .replace(reToken, function (match) {
+      return snippets.shift()
+    })
+    .trim()
+}
+
+/**
+ * Parses the JSDoc `comment` into an object.
+ * @memberOf util
+ * @param {string} comment The comment to parse.
+ * @returns {object} Returns the parsed object.
+ */
+export const parse = _.partial(doctrine.parse, _, {
+  lineNumbers: true,
+  recoverable: true,
+  sloppy: true,
+  unwrap: true
+})