5

我认为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 的存在，并且对此非常陌生。

4

1 回答 1

4

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

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

单元测试命名空间

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

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

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

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

例子来了。

1：添加一个@namespace

添加@namespacetoPluginTests将导致另一个名称空间页面，专门用于PluginTests，并将包含您需要的信息：

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您可以在PluginTestsdoclet中记录该属性，而不是创建另一个命名空间：

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

于 2015-12-28T16:26:40.360 回答