JSDoc: Why aren't my nested objects links (why aren't they click-able)?

Question

I would think that all members / objects / etc. documented by JSDoc should be their own click-able links; e.g., if I have levelOne --> levelTwo --> levelThree --> levelFour, then I should see levelOne on the first page and be able to click my way through to levelFour...but that doesn't seem to be the case.

Here is my code:

/**
    Contains various tools and extensions.
    @namespace App
    */
var app = app || {};


/**
Contains App plugins.
@namespace App.Plugins
*/
app.Plugins = app.Plugins || {};

/**
Contains methods and classes usable within unit-testing.
@memberof App
@type {object}
@namespace App.UnitTesting
*/
app.UnitTesting = app.UnitTesting || {
    /**
    Test methods for the App library.
    @memberof App.UnitTesting
    @type {object}
    @property {object} test1 Property definition.
    */
    PluginTests: {
        /** 
        Test for this or that
        @memberof App.UnitTesting.PluginTests
        @type {object}
        @property {method} innertest1 Property definition for "innertest1"
        */
        test1: {
            /**
            Run another nested test
            @memberof App.UnitTesting.PluginTests.test1
            @method innertest1
            @returns {object}
            */
            innertest1: function () { }
        }
    }
};

The "namespace" objects are easily clickable, and are accessible from the home page, but PluginTests IS NOT CLICKABLE (IT ISN'T A LINK!!), and therefore test1 and innertest1 are not accessible. Am I grossly misunderstanding how JSDoc works?

---

PS: Before anyone starts tearing apart my code with hurtful comments, please note that I learned of JSDoc's existence about 3 hours ago and am very new to this.

Answer 1

As far as I know, JSDoc doesn't generate pages for all or an arbitrary property. You might expect JSDoc to generate pages for deeply nested object properties automatically, but that isn't the case. For example, there is an open issue on Github on making it easier to link to object properties.

The JSDoc output for the UnitTesting namespace in the code you provided looks as following (using the default template):

I assume that you expected the property test1 to be clickable and that it would lead you to a page providing information on test1 (eg. the fact that it has a method innertest1). Unfortunately, that isn't the case.

The way code is documented is slightly related to its architecture (eg. JSDoc provides support for classes, modules, mixins, namespaces, and so on). In my experience, good architecture helps writing neat documentation. The JSDoc template you use might influence how your perceive hierarchy. For example: some templates create a tree of namespaces.

Anyway, in this particular example/architecture, your options are:

1. Adding another @namespace for PluginTests.
2. Adding a @property entry for innertest1 in the PluginTests doclet.

Examples coming up.

1: Add a @namespace

Adding a @namespace to PluginTests would result in another namespace page, specifically for PluginTests, and would include the information you need:

The change to the code you provided is obvious, yet I'll just include the part that changed for the sake of completeness:

/**
 * Test methods for the App library.
 * @namespace App.UnitTesting.PluginTests
 * @memberof App.UnitTesting
 * @type {object}
 * @property {object} test1 Property definition.
 */
PluginTests: {}

2: Add @property for innertest1

Instead of creating another namespace, you could document the property test1.innertest1 in the PluginTests doclet:

/**
 * Test methods for the App library.
 * @memberof App.UnitTesting
 * @type {object}
 * @property {object} test1 Property definition.
 * @property {method} test1.innertest1 A method.
 */
PluginTests: {}

This would result in an extra property table inside the description of test1:

Side note

You might like using the Baseline template to format your documentation. It's still under active development (by Googlers) and subject to change. One of the reasons I occasionally use it: it's easier to navigate. From the docs:

An expandable table of contents helps users find what they're looking for. Also, a summary at the top of each page shows users what's documented on that page.

One downside is that Baseline doesn't support the second option yet.