JSDoc：为什么我的嵌套对象没有链接（为什么它们不能点击）？

Question

我认为JSDoc记录的所有成员/对象/等应该是他们自己的可点击链接;例如，如果我有levelOne --> levelTwo --> levelThree --> levelFour，那么我应该在第一页上看到levelOne，并且能够点击我的方式进入levelFour ......但似乎并非如此。

这是我的代码：

/**
    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 () { }
        }
    }
};

＆＃34;命名空间＆＃34;对象很容易点击，并且可以从主页访问，但是PluginTests 不可点击（它不是！@）; ，因此test1和{ {1}}无法访问。我是否误解了JSDoc的工作方式？

PS：在任何人开始用有害的评论撕开我的代码之前，请注意我在3个小时前就已经了解了JSDoc的存在并且对此非常了解。

Answer 1

据我所知，JSDoc不为所有或任意属性生成页面。您可能希望JSDoc自动生成深层嵌套对象属性的页面，但事实并非如此。例如，Github上有一个未解决的问题making it easier to link to object properties。

您提供的代码中UnitTesting命名空间的JSDoc输出如下所示（使用默认模板）：

我假设您希望属性test1可以点击，并且它会引导您访问提供test1信息的页面（例如，它有一个方法innertest1 ）。不幸的是，事实并非如此。

记录代码的方式与其体系结构略有关系（例如，JSDoc提供对类，模块，混合，命名空间等的支持）。根据我的经验，良好的架构有助于编写简洁的文档。您使用的JSDoc模板可能会影响您的感知层次结构。例如：一些模板创建一个命名空间树。

无论如何，在这个特定的示例/架构中，您的选项是：

1. 为@namespace添加另一个PluginTests。
2. 在@property doclet中为innertest1添加PluginTests条目。

即将出现的例子。

1：添加@namespace

将@namespace添加到PluginTests会导致另一个命名空间页面，特别是PluginTests，并且会包含您需要的信息：



您提供的代码更改很明显，但为了完整起见，我只会包含更改的部分：

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

2：为@property

添加innertest1

您可以在test1.innertest1 doclet中记录属性PluginTests，而不是创建另一个名称空间：

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

这会在test1的描述中产生额外的属性表 ：



旁注

您可能希望使用Baseline template格式化文档。它仍在积极开发中（由Google员工）并且可能会发生变化。我偶尔使用它的原因之一：它更容易导航。来自文档：

  

可扩展的目录可帮助用户找到他们正在寻找的内容。此外，每页顶部的摘要向用户显示该页面上记录的内容。

一个缺点是Baseline还不支持第二个选项。