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不可点击（它不是一个链接！！），因此test1和innertest1无法访问。我是否完全误解了JSDoc的工作原理？

---

PS：在任何人用伤人的言语批评我的代码之前，请注意我关于JSDoc的存在是在大约3个小时前得知的，我非常新手。

- Ross Brasseaux

---

我不确定你想要实现什么，能否解释一下你期望的结果与实际结果有何差异（截图可能会有帮助）？ - oshnaps

@oshnaps 基本上，我想能够指定某些非命名空间、非全局对象拥有自己的页面，以便我可以链接到该页面。我想对于那些类型的对象，我可以创建一个完全独立和不相关的对象，然后定义一个别名，并将其放置在相应的属性标签上作为链接。 - Ross Brasseaux

Answer 1

据我所知，JSDoc不会为所有或任意属性生成页面。您可能希望JSDoc自动为深度嵌套的对象属性生成页面，但事实并非如此。例如，在Github上有一个未解决的问题（使链接到对象属性更容易）。

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

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

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

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

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

接下来会有示例。

1：添加@namespace

向PluginTests添加@namespace将导致另一个命名空间页面，专门针对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文档中说明属性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尚不支持第二个选项。

- pesla