javascript - JSDoc 侧边栏中的嵌套方法

Question

感谢在这里找到的答案:

https://stackoverflow.com/a/19336366/592495

我的 JavaScript 文档组织良好且格式正确。每个 namespace 都是其中包含的方法的“父级”。但是，导航并不像我希望的那样精细。

在通过一个简单的命令(jsdoc file1.js file2.js)使用 node.js 工具编译/渲染后，文档将生成到默认模板中。此默认模板在侧边栏导航中显示我的命名空间，但它不显示每个包含的方法。

您可以通过向每个方法添加 @class 指令来伪造一个方法列表，但正如我们所知，它们并不是真正的类。

我希望看到这样的侧边栏导航:

My Project

 - namespace 1
    - method.a
    - method.b
    - method.c

 -namespace 2
    - method.d
    - method.e

任何我忽略的文档指导都将不胜感激。

---

[编辑添加:]

经过实验，@class 几乎完全符合我的要求，但有一些异常(exception):

• 它列出了命名空间之上的类。我不喜欢这样，因为 namespace 实际上是“ parent ”。

• JavaScript 没有那种意义上的类。不是那些被称为“类”的术语。当阅读文档以查看“类”列表时，它会产生奇怪的断开连接。

• 它会自动添加“new”运算符。并非所有方法都有构造函数……您可以看出问题所在!

---

[编辑:示例代码]

这是当前的结构。在我用 JSDoc 注释对其进行注释之前，这里是基本方法:

var app =  app || {};
app.utils = {
    whizbang: function() {},
    geegolly: function() {}
  };
app.render = {
    thestuff: function(params) {},
    thethings: function(params) {}
  }
}

因此，使用对象字面量表示法，顶层是整个应用程序的“命名空间”，但其中有用于不同目的的子命名空间。在这里，我有一个特定于实用程序的子命名空间，以及另一个特定于渲染的子命名空间。每个都可以有属性，但更重要的是它们每个都包含功能。这些功能应该出现在侧边栏中。现在用我当前的 JSDoc 模式充实它:

/** 
 * @file MyApp.js This is an awesome description of MyApp.js
 * 
 * @version 0.1
 * @author Greg Pettit
 * @copyright 2015
 * 
 */

/**
 * Description of my main namespace!
 * 
 * @namespace app
 */
var app = app || {};

/**
 * This is a description of my sweet utilities namespace!
 *                                                                              
 * @memberof app
 * @type {object}
 * @namespace app.utils
 */
app.utils = {
  /**
   * app.utils.whizbang is an awesome function with magical powers. I sure wish
   * it would appear in the sidebar as a member of app.utils!
   * 
   * @memberof app.utils
   * @method whizbang
   * 
   * @param {method} [successCallback] Method invoked on successful attempt.
   * @param {method} [errorCallback] Method invoked on unsuccessful attempt.
   * 
   */
   whizbang: function(successCallback, errorCallback) { // do utility stuff! }
}

/**
 * This is a description of the best rendering namespace ever.
 *                                                                              
 * @memberof app
 * @type {object}
 * @namespace app.render
 */
app.render = {
  /**
   * app.render.thethings renders the things! I wish it would render to the sidebar...
   * 
   * @memberof app.render
   * @method thethings
   * 
   * @param {method} node The node to which thethings are rendered
   * 
   */
   thethings: function(node) { // do rendering stuff! }
}

Answer 1

您是否尝试过使用 @lends 标签？您的代码示例和文档注释在这里会很有帮助。

由于我不知道您的代码是什么样的，所以我将举例说明我如何将 JSDoc 与我们的内部框架一起使用，该框架有很多特殊之处(嘿，我没有写，我只需要使用它)。

只是为了提供一些上下文，我们有一个可以创建应用程序和模块的 context 对象(应用程序只是具有 start 方法的模块):

/** @namespace MyApp */
var MyApp = context.app('myApp').use('module1', 'module2', 'underscore');

我们有一个用于主干的依赖注入(inject)系统，它使用 Angular 样式模式来表达依赖关系:

/** 
* The constructor for MyModel
* @memberof MyApp
* @param {object?} attrs
* @param {object?} options
* @param {AppUtils} appUtils
* @constructor
*/  
MyApp.MyModel = function(attrs, options, appUtils) {
    this.options = options;
    this.utils = appUtils;
}

// This is injected by the dependency resolver at instantiation time
// No additional JSDoc comments are necessary, it actually gets this right
MyApp.MyModel.prototype = {

    idAttribute: 'customId',

    defaults: {
        customId: '',
        name: '',
        birthday: null
    }

};

// Registers MyModel with the IOC container as 'myModelName'
MyApp.model('myModelName', [
    'attrs',
    'options',
    'appUtils'
    MyApp.MyModel
]);

然后一个不同的文件可以通过将它添加到底部的依赖数组来注入(inject)一个 myModelName 的实例。

有趣的是，JSDoc 实际上在理解特定安排方面做得很好，只要我不想太花哨......但以下模式显然对它来说太困惑了:

/**
 * @memberof MyApp
 * @param {MyApp.MyModel} myModel
 * @param {urlParser} urlParser
 * @constructor
 */
MyApp.SomeService = function(myModel, urlParser) {

    return {

        foo: function() {
            //whatever
        },

        bar: function() {
            //whatever
        }

    };

};

MyApp.service('someModuleName', [
    'myModelName',
    'urlParser',
    MyApp.SomeService
]);

我发现唯一能给我任何接近所需输出的东西是使用@lends 标记告诉 JSDoc 特定对象/属性/方法作为不同的属性“借出”。例如，要记录 Backbone 模型的 attributes 属性(表面上由其 defaults 属性定义)，我们这样做:

MyApp.MyModel.prototype = {

    idAttribute: 'customId',

    /** @lends MyApp.MyModel.prototype.attributes */
    defaults: {
        customId: '',
        name: '',
        birthday: null
    }

};

对于服务返回对象的情况，我们发现记录这些对象属性的唯一方法是这样的:

/**
 * @memberof MyApp
 * @param {MyApp.MyModel} myModel
 * @param {urlParser} urlParser
 * @constructor
 */
MyApp.SomeService = function(myModel, urlParser) {

    /** @lends  MyApp.SomeService.prototype */
    return {

        foo: function() {
            //whatever
        },

        bar: function() {
            //whatever
        }
    };

};

我不知道这些是否有用，但也许它会给你一些想法，让你可以尝试使用 @lends。如果您能提供一些示例代码，我可能会给您更有用的答案。