mozilla / sphinx-js

Autodoc-style extraction into Sphinx for your JS project
https://pypi.python.org/pypi/sphinx-js/
MIT License
282 stars 81 forks source link

Add support for JSDocs @namespace tag #176

Open xsjad0 opened 3 years ago

xsjad0 commented 3 years ago

Instead of using classes to encapsulate some JS code we often use namespaces. To document namespaces JSDoc offers the @namespace tag. The documentation looks quite similar to a class documentation. At first glance, there's just another prefix (namespace instead of class).

Example JS code

/**
 * A simple namespace.
 * @namespace
 */
var NewNamespace = {
    /** documented as NewNamespace.someAttribute. */
    someAttribute : "foo",

    /**
     * documented as NewNamespace.foo
     * @returns {void}
     */
    foo : function() {},

    /**
     * @returns {void}
     */
    bar : function() {},

    /**
     * @private
     * @returns {void}
     */
    baz : function() {},
};

Document namespace like this

.. js:autonamespace:: NewNamespace
    :members:
    :private-members:
    :exclude-members: bar

Generated output

image

Notable changes are:

I'm not sure, if this directive is going to be used by a lot of people. We just wanted to see a slightly different documentation for classes and namespaces. In addition, the changes do no harm on the rest of the code^^