Targetprocess-jsdoc-gen NPM

JsDoc Markdown documentation generator

This tool is a simple node.js console utility based on awesome jsdoc2md for generating markdown files per module based on JsDoc documentation. Each module is split to a separate markdown file, and an additional index file is generated with list of all found modules.

Additionaly, the generator makes some heuristic assumptions about parsed JsDoc:

Every definition that requires documenting belongs to a @module. Global JsDoc annotations (i.e. JsDoc in files without @module declaration) are ignored
@properties, @params and @returns type specifications (i.e. @class, @typedef and @callback annotations) are assumed to belong to current module, if they appear within it. As a result, there is no need to use fully-qualified names for module-scoped typedefs (resolves https://github.com/jsdoc3/jsdoc/issues/969)
All module-scoped class members are re-attached to static-scoped class, if static-scoped class with the same name is present in module. This fixes incorrect class member documentation for export class definitions (https://github.com/jsdoc3/jsdoc/issues/1137)

Usage

Basic usage:

> targetprocess-jsdoc-gen -i <input file pattern> -o <output directory>

Command line arguments:

Argument	Description
`-i`,`--input`	Input file or file glob pattern. Typically wildcard pattern can be used, i.e. `tau/scripts/tau/api/*/.js`
`-o`,`--output`	Output directory path
`--index`	Index file name, defaults to `index.md`.
`--title`	Title generated for index file, defaults to `Targetprocess API documentation`
`--footnote`	An optional footnote that will be inserted at the end of index file

Output will generate a folder structure based on module names, so if, for example, input files define @module my/module, output will contains index.md file and module.md file in my subdir.

All links in index are relative, so output can be stored in source control as is.

A common usage scenario is using generator as a pre-commit hook.

JsDoc guidelines

Always use @module declaration in files. Documentation for globals is not generated by default.
Use fully-qualified module names that correspond to actual usage of the documented module. For example, if target code imports a specific module as tau/api/acid/v1, that should be the module name.
Use @typicalname to make module member names a bit more friendly to read. I.e. module may be named underscore, but for clarity in documentation, its @typicalname can be set to _.
Use camelCase and slash/separated/namespaces for module names. Avoid dots and dashes.
Use @typedef for complex objects in parameters and return values.
Prefer ES2015 classes and modules instead of other module and class systems where possible. They are better processed by JsDoc. You may need @class and @memberOf tags to describe literal object as class.
Use @callback to document callback functions. Make callback a part of class if callback is used only inside that class

Example:

/**
 * Some client side API version 1.
 * @module tau/api/clientSideApi/v1 
 * @typicalname clientSideApi
 */

/** 
 * Some callback.
 * @callback someMethodCallback
 * @param {string} callbackParam - param
 */

/**
 * Some class.
 */
export class MyClass {
    /**
     * Creates a new MyClass instance based on number
     * @param {number} x - some input number
     */
    constructor(x) {
    }

    /** 
     * Registers some callback 
     * @param {someMethodCallback} callback - callback parameter
     */ 
    someMethod(callback) {
    }

    /**
     * Some static method of MyClass
     */
    static someStaticMethod() {
    }
} 

/**
 * Some very complex type
 * @typedef ComplexType
 * @param {string} someParam - some parameter
 * @param {number} otherParam - other parameter
 */

/** 
 * @function
 * @param {MyClass} myClassInstance - some description
 * @returns {ComplexType} - description of returned value
 */
export function someFunction(myClassInstance) {}

The above example produces the following output for module tau/api/clientSideApi/v1: