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

“命名空间”对象很容易点击，并且可以从主页访问，但PluginTests 不可点击（它不是链接！！），因此test1和innertest1 不可访问。我是否严重误解了 JSDoc 的工作原理？

---

PS：在有人开始用有害的 cmets 拆解我的代码之前，请注意，我在大约 3 小时前了解到 JSDoc 的存在并且对此非常陌生。

Answer 1

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

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

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

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

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

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

示例即将推出。

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：为innertest1 添加@property

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

/**
 * 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 还不支持第二个选项。