targetprocess-jsdoc-gen

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:

tau/api/clientSideApi/v1

Some client side API version 1.

• tau/api/clientSideApi/v1
  • static
    • .MyClass
      • new MyClass(x)
      • instance
        • .someMethod(callback)
      • static
        • .someStaticMethod()
    • .someFunction(myClassInstance) ⇒ ComplexType
  • inner
    • ~someMethodCallback : function
    • ~ComplexType

clientSideApi.MyClass

Some class.

Kind: static class of tau/api/clientSideApi/v1

• .MyClass
  • new MyClass(x)
  • instance
    • .someMethod(callback)
  • static
    • .someStaticMethod()

new MyClass(x)

Creates a new MyClass instance based on number

Param	Type	Description
x	number	some input number

myClass.someMethod(callback)

Registers some callback

Kind: instance method of MyClass

Param	Type	Description
callback	someMethodCallback	callback parameter

MyClass.someStaticMethod()

Some static method of MyClass

Kind: static method of MyClass

clientSideApi.someFunction(myClassInstance) ⇒ ComplexType

Kind: static method of tau/api/clientSideApi/v1
Returns: ComplexType - - description of returned value

Param	Type	Description
myClassInstance	MyClass	some description

tau/api/clientSideApi/v1~someMethodCallback : function

Some callback.

Kind: inner typedef of tau/api/clientSideApi/v1

Param	Type	Description
callbackParam	string	param

tau/api/clientSideApi/v1~ComplexType

Some very complex type

Kind: inner typedef of tau/api/clientSideApi/v1

Param	Type	Description
someParam	string	some parameter
otherParam	number	other parameter