automatic module documentation with js:automodule

[xsjad0]

js:automodule - directive

Hey Erik! I have another feature that I want to share with you and others. With this pull request, I'm going to address issue #5 .

JSDoc provides the @module tag that marks the current file as being its own JS module (see JSDoc documentation). With the @module tag, we tell JSDoc that all symbols in the path are assumed to be members of that module. Additionally, you can use the @author, @version and @license tags to display some more information in the module comment. Once we've done this, we can use the js:automodule directive to document the JS module with all its members at once.

Here's an example:

JS module containing some constants, classes and functions

/**
 * For test purpose only.
 *
 * @module  TestModule
 * @author  xsjad0
 * @version 0.1.0
 * @license MIT
 */

/**
 * Class doc.
 */
 class SimpleClass {
    /**
     * Constructor doc.
     */
    constructor() {}

    /**
     * simpleMethod.
     */
    simpleMethod() {}

    /**
     * privateMethod
     * @private
     */
    privateMethod() {}

    /**
     * simpleAttribute.
     */
    simpleAttribute = "attr"
}

/**
 * simpleFunction.
 */
function simpleFunction() {}

/**
 * globalConstant.
 */
const globalConstant = null;

Text to trigger the module documentation

TestModule
==========

.. js:automodule:: TestModule
    :members:

HTML output

The js:automodule directive accepts the options :members:, :private-members: and :exclude-members to handle what needs to be documented. These options work on module and on class level. That means that you can control class members as well as module members (maybe there's an even better approach?!)

The additional tags @author, @version and @license can be omitted.

Notes:

• The syntax of the @module tag differs from the syntax described in JSDocs documentation
  • @module <moduleName> instead of @module [[<type>] <moduleName>]
  • I'm not sure why we would need this?!
• order of the symbols
  • classes
  • attributes
  • methods
  • members/constants (attributes)
  • functions

Notable changes:

• add some tests
• extend readme
• collect doclets by module
• register automodule directive
• add renderer AutoModuleRenderer
• add ir dataclass Module
• add template module.rst

We need to document many classes, namespaces, functions, ... This features safes us a lot of time! I also started to implement an automodules directive, which makes it even possible to document multiple modules at once. But first, I want to read your opinion about this feature. Hope you gonna enjoy it!