@enterthenamehere/esdoc-monorepo

Welcome to @enterthenamehere/esdoc-monorepo

Original ESDoc is unfortunately no more mantained, so it will break generation of documentation if you use any ESNext feature in your code. That's why I've updated ESDoc and it's plugins and for ease of maintaining the whole suite put it into a single monorepository.

What's new/different from ESDoc?

• New scope: all my packages are under @enterthenamehere/ scope;
• Moved "core" of ESDoc documentation generation functionality into it's own package: esdoc-core;
• Updated to babel 7, enabling parsing of ESNext features;
• Added esdoc-ecmascript-proposal-plugin to esdoc-standard-plugin, so you can use ESNext right away;
• Updated dependencies to get rid of high risk vulnerabilities;
• Replaced prettify with highlight.js - it's not 100% replacement though, so if you see issues, do tell;
• Monorepository is using lerna;

Install

So how do I use your version of ESDoc?

npm install @enterthenamehere/esdoc @enterthenamehere/esdoc-standard-plugin

and you can run esdoc by

npx esdoc

or use it in npm "script"

{
    "scripts": {
        "esdoc": "esdoc"
    }
}

Config

esdoc.json

{
    "source": "./src",
    "destination": "./docs",
    "plugins": [{"name": "esdoc-standard-plugin"}]
}

No need to use @enterthenamehere/esdoc-standard-plugin in config anymore! No need to change configs. You still need to use @enterthenamehere/ when installing packages with npm though.

Plugins

You probably want to install esdoc-standard-plugin pack.

It contains these plugins:

Plugin	Description
esdoc-accessor-plugin	You can specify if you want private identifiers in documentation.
esdoc-brand-plugin	Cool features like describing your package, a logo, or... repository url.
esdoc-coverage-plugin	Information like: you have only 4 of 20 identifiers in this file documented.
esdoc-ecmascript-proposal-plugin	Makes ESDoc parse ESNext code.
esdoc-external-ecmascript-plugin	Recognizes ECMAScript objects and point to MDN docs.
esdoc-integrate-manual-plugin	You can specify files which will make a manual section.
esdoc-integrate-test-plugin	Links tests to objects they test.
esdoc-lint-plugin	Checks if there is a mismatch between documentation and code, like in function signatures.
esdoc-publish-html-plugin	The real deal: Generates HTML for viewing in your favorite browser.
esdoc-type-inference-plugin	Guesses identifier's type in case it's not specified.
esdoc-undocumented-identifier-plugin	If you don't want to have unexported identifiers in docs.
esdoc-unexported-identifier-plugin	If you don't want to have unexported identifiers in docs.

Just use

npm install @enterthenamehere/esdoc-standard-plugin

Additional plugins

ESDoc offers even more plugins, but you have to install these individually:

Plugin	Description
esdoc-exclude-source-plugin	Do not add source code files into documentation.
esdoc-external-nodejs-plugin	Makes ESDoc recognize Node.js identifiers and point to their manual.
esdoc-external-webapi-plugin	Makes ESDoc recognize WebAPI identifiers and point to their manual.
esdoc-flow-type-plugin	Makes ESDoc parse and document Flow.
esdoc-inject-gtm-plugin	Injects Google Tag Manager. (I don't know how that works...)
esdoc-inject-script-plugin	Injects script into HTML layout.
esdoc-inject-style-plugin	Injects style into HTML layout.
esdoc-importpath-plugin	Renames directories/files based on a pattern.
esdoc-publish-markdown-plugin	Generates documentation as markdown.
esdoc-react-plugin	Makes ESDoc parse React.
esdoc-jsx-plugin	Makes ESDoc parse JSX.
esdoc-typescript-plugin	Makes ESDoc parse TypeScript.

Tags

ESDoc recognizes following tags:

Tags
@abstract	@access	@deprecated	@desc	@emits	@example
@experimental	@extends	@ignore	@implements	@interface	@lineNumber
@link	@listens	@override	@package	@param	@private
@property	@protected	@public	@returns	@see	@since
@test	@throws	@todo	@type	@typedef	@version

/**
 * A sentence someone said.
 * @example
 * const message = new Sentence('Dark Helmet', 'I knew it, I\'m surrounded by assholes!');
 * 
 * @see https://www.imdb.com/title/tt0094012/
 */
export class Sentence {
  /**
   * Stores name of person who said the sentence.
   * @type {string}
   * @private
   */
  User;
  
  /**
   * Sentence that was said.
   * No need to use @private if autoprivate is `on` (which is by default).
   * If identifier starts with `_` it's private automagically.
   * @type {string}
   */
  _Sentence;

  /**
   * Creates new instance of Message
   * @param {string} user    - Who said said message.
   * @param {string} message - said message.
   * @throws {Error} - if `sentence` contains a naughty word.
   */
  constructor( user, sentence ) {
    if( sentence.includes('fuck') ) throw new Error('No swearing!');
    
    this.User = user;
    this._Sentence = message;
  }
  
  /**
   * Returns what was said.
   * @returns {string} - the sentence
   */
  whatWasTheMessageAgain() {
    return this._Sentence;
  }
  
  /**
   * @todo This function doesn't belong here... Move it to {@link Engine}.
   * Use ignore tag so this function isn't in documentation until then...
   * @ignore
   */
  engageLudicrousSpeed() {}
  
  /**
   * @returns {Radar}
   */
  noBleepsNoSweepsNoCreeps() {
    return new Radar({ jammed: true });
  }
}

/**
 * @typedef {object} Radar 
 * @property {boolean} jammed - `true` if Radar appears to be jammed.
 */

You can also use @param {number} [theAnswerToLifeTheUniverseAndEverything=42] to document the parameter is [optional] and it's default value is 42. Read more about type syntax.

LICENSE

MIT

Thank you goes to author of ESDoc

Ryo Maruyama@h13i32maru