JSDoc: Why are my links to nested objects (why are they not accessible to clicks)?

Question

I would think that all participants / objects, etc., documented by JSDoc, should be their own click links; for example, if I have levelOne --> levelTwo --> levelThree --> levelFour , then I should see levelOne on the first page and be able to click my path 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 () { } } } }; 

Namespace objects are easily PluginTests and accessible from the home page, but PluginTests DO NOT CLIMATE (NOT LINE !!) and therefore test1 and innertest1 not available. I greatly misunderstand how JSDoc works?

---

PS: Before anyone starts breaking my code with offensive comments, please note that I found out about the existence of JSDoc about 3 hours ago and is very new to this.

Answer 1

As far as I know, JSDoc does not create pages for all or any property. You can expect JSDoc to automatically create pages for the deeply nested properties of the object, but this is not the case. For example, there is an open problem on Github: simplifying the link to the properties of an object .

The JSDoc output for the UnitTesting namespace in the code you submitted is as follows (using the default template):

I assume that you expected the test1 property to be clickable and that it will lead you to a page containing information about test1 (for example, that it has an innertest1 method). Unfortunately, this is not the case.

The documented code path is slightly related to its architecture (for example, JSDoc provides support for classes, modules, mixins, namespaces, etc.). In my experience, good architecture helps write accurate documentation. The JSDoc template you use may affect your perception hierarchy. For example: some templates create a namespace tree.

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

• Adding another @namespace for PluginTests .
• Adding an @property entry for innertest1 to the PluginTests .

Examples.

1: add @namespace

Adding @namespace to PluginTests will lead to another page of the namespace, in particular for PluginTests , and will contain the necessary information:

The change to the code you provided is obvious, but I will just include the part that has been modified for 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 to innertest1

Instead of creating another namespace, you can write the property test1.innertest1 in the PluginTests :

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

This will add an additional property table to the description of test1 :

Side note

You may need to use a basic template to format your documentation. It is still being actively developed (by Googlers) and is subject to change. One of the reasons I sometimes use them is: it's easier to navigate. From the docs:

An extensible table of contents helps users find what they are looking for. In addition, a summary at the top of each page shows users what is documented on this page.

The only drawback is that Baseline does not yet support the second option.