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

"namespace" 对象很容易点击，并且可以从主页访问，但是 PluginTests 不可点击（它不是 LINK！ !)，因此无法访问 test1 和 innertest1。我是否严重误解了 JSDoc 的工作原理？

PS：在任何人开始用有害的评论撕毁我的代码之前，请注意我大约 3 小时前才知道 JSDoc 的存在，而且我对此还很陌生。

Answer 1

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

上的 Github 上有一个未解决的问题

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

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

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

无论如何，在这个特定的 example/architecture 中，您的选择是：

为 PluginTests 添加另一个 @namespace。
在 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: {}

这将导致属性 table 在的描述 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 尚不支持第二个选项。

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

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

javascript

documentation-generation

javascript-objects

jsdoc

jsdoc3

1：添加一个`@namespace`

2：为`innertest1`

旁注

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

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

javascript

documentation-generation

javascript-objects

jsdoc

jsdoc3

1：添加一个@namespace

2：为innertest1

旁注

1：添加一个`@namespace`

2：为`innertest1`