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 无法点击(它不是一个LINK!) ,因此test1并innertest1无法访问.我是否误解了JSDoc的工作方式？

---

PS:在任何人开始用有害的评论撕开我的代码之前,请注意我在大约3小时前了解到JSDoc的存在并且对此非常新.

Answer 1

据我所知，JSDoc 不会为所有或任意属性生成页面。您可能期望 JSDoc 自动生成深层嵌套对象属性的页面，但事实并非如此。例如，Github 上有一个关于如何更轻松地链接到对象属性的开放问题。

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

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

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

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

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

例子即将出现。

1：添加一个@namespace

添加@namespacetoPluginTests将导致另一个命名空间页面，专门用于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：

边注

您可能喜欢使用基线模板来格式化您的文档。它仍在积极开发中（由 Google 员工进行），并且可能会发生变化。我偶尔使用它的原因之一：它更容易导航。来自文档：

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

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