Skip to content
This repository has been archived by the owner on Jan 8, 2025. It is now read-only.

Add support for JSDocs @namespace tag #176

Closed
wants to merge 12 commits into from

Conversation

xsjad0
Copy link

@xsjad0 xsjad0 commented May 5, 2021

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:

  • add template namespace.rst
    • similar to class.rst
    • no supers, no interface, no is_interface, no is_static
  • add directives namespace and autonamespace to js domain
    • autonamespace and autoclass have the same options
  • add ir class Namespace
  • collect doclets by namespace
  • add renderer AutoNamespaceRenderer
  • write some tests (very similar to autoclass tests)

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^^

mariusschenzle added 12 commits May 3, 2021 17:15
* add template namespace.rst (similar to class.rst
* add directive AutoNamespaceDirective
* add role ns
* add object type namespace
* add renderer AutoNamespaceRenderer
* extend intermediate representation with a namespace dataclass
* collect doclets by namespace in jsdoc analyzer class
* write some tests
* add how to use js:autonamespace directive
* how to reference a namespace
* add prefix static in front of namespace methods
@willkg willkg added this to the 3.2 milestone Feb 23, 2022
@willkg willkg modified the milestones: 3.2.0, 3.next Dec 13, 2022
hoodmane added a commit to hoodmane/sphinx-js that referenced this pull request Dec 23, 2024
@willkg
Copy link
Member

willkg commented Dec 31, 2024

I'm sorry, but we're shutting down this project. You could look at making these changes to sphinx-js-fork if they're not made already. Thank you!

@willkg willkg closed this Dec 31, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants