javascript - 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:在有人开始用伤人的评论拆解我的代码之前，请注意我大约 3 小时前才知道 JSDoc 的存在，对此我还是很陌生。

Answer 1

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

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

我假设您希望属性 test1 是可点击的，它会将您带到一个提供有关 test1 的信息的页面(例如，它有一个方法 innertest1)。不幸的是，情况并非如此。

代码的文档化方式与其架构略有相关(例如，JSDoc 提供对类、模块、混合、命名空间等的支持)。根据我的经验，良好的架构有助于编写整洁的文档。您使用的 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 员工)积极开发中，并且可能会发生变化。我偶尔使用它的原因之一是:它更容易导航。来自文档:

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.

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