sphinx-js 1.5

autofunction

Document your JS code using standard JSDoc formatting:

/**
 * Return the ratio of the inline text length of the links in an element to
 * the inline text length of the entire element.
 *
 * @param {Node} node - Types or not: either works.
 * @throws {PartyError|Hearty} Multiple types work fine.
 * @returns {Number} Types and descriptions are both supported.
 */
function linkDensity(node) {
    const length = node.flavors.get('paragraphish').inlineLength;
    const lengthWithoutLinks = inlineTextLength(node.element,
                                                element => element.tagName !== 'A');
    return (length - lengthWithoutLinks) / length;
}

Our directives work much like Sphinx’s standard autodoc ones. You can specify just a function:

.. js:autofunction:: someFunction

Or you can throw in your own explicit parameter list, if you want to note optional parameters:

.. js:autofunction:: someFunction(foo, bar[, baz])

You can even add additional content. If you do, it will appear just below any extracted documentation:

.. js:autofunction:: someFunction

    Here are some things that will appear...

    * Below
    * The
    * Extracted
    * Docs

    Enjoy!

Use JSDoc namepath syntax to disambiguate same-named entities:

.. js:autofunction:: SomeClass#someInstanceMethod

Behind the scenes, sphinx-js will changes those to dotted names so that…

• Sphinx’s “shortening” syntax works: :func:`~InwardRhs.atMost` prints as merely atMost(). (For now, you should always use dots rather than other namepath separators: #~.)

• Sphinx indexes more informatively, saying methods belong to their classes.

To save some keystrokes, you can set primary_domain = 'js' in conf.py and then say simply autofunction rather than js:autofunction.

js:autofunction has one option, :short-name:, which comes in handy for chained APIs whose implementation details you want to keep out of sight. When you use it on a class method, the containing class won’t be mentioned in the docs, the function will appear under its short name in indices, and cross references must use the short name as well (:func:`someFunction`):

.. js:autofunction:: someClass#someFunction
   :short-name:

autoclass

We provide a js:autoclass directive which documents a class with the concatenation of its class comment and its constructor comment. It shares all the features of js:autofunction and even takes the same :short-name: flag, which can come in handy for inner classes. The easiest way to use it is to invoke the :members: option, which automatically documents all your class’s public methods and attributes:

.. js:autoclass:: SomeEs6Class(constructor, args, if, you[, wish])
   :members:

You can add private members by saying…

.. js:autoclass:: SomeEs6Class
   :members:
   :private-members:

Privacy is determined by JSDoc @private tags.

Exclude certain members by name with :exclude-members::

.. js:autoclass:: SomeEs6Class
   :members:
   :exclude-members: Foo, bar, baz

Or explicitly list the members you want. We will respect your ordering.

.. js:autoclass:: SomeEs6Class
   :members: Qux, qum

Finally, if you want full control, pull your class members in one at a time by embedding js:autofunction or js:autoattribute:

.. js:autoclass:: SomeEs6Class

   .. js:autofunction:: SomeEs6Class#someMethod

   Additional content can go here and appears below the in-code comments,
   allowing you to intersperse long prose passages and examples that you
   don't want in your code.

autoattribute

This is useful for documenting public properties:

class Fnode {
    constructor(element) {
        /**
         * The raw DOM element this wrapper describes
         */
        this.element = element;
    }
}

And then, in the docs…

.. autoclass:: Fnode

   .. autoattribute:: Fnode#element

This is also the way to document ES6-style getters and setters, as it omits the trailing () of a function. The assumed practice is the usual JSDoc one: document only one of your getter/setter pair:

class Bing {
    /** The bong of the bing */
    get bong() {
        return this._bong;
    }

    set bong(newBong) {
        this._bong = newBong * 2;
    }
}

And then, in the docs…

.. autoattribute:: Bing#bong