JSDoc侧栏中的嵌套方法

Question

感谢这里找到的答案:

/sf/answers/1353545651/

我的JavaScript文档组织良好,格式正确.每个命名空间都是其中包含的方法的"父".但是,导航并不像我想的那样精细.

通过简单的命令(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几乎完全符合我的要求,但有一些例外:

• 它列出了名称空间之上的类.我不喜欢这样,因为名称空间是"父母".

• JavaScript在这个意义上没有类.不是那种被称为"类"的命名法.在阅读文档以查看"类"列表时,它会创建一个奇怪的断开连接.

• 它自动添加"新"运算符.并非所有方法都有构造函数......你可以看到问题!

---

[编辑:示例代码]

所以这是目前的结构.在我使用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');

我们有一个主干依赖注入系统，它使用角度样式模式来表达依赖关系：

/** 
* 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
]);

然后，可以通过将 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 特定的对象/属性/方法作为不同的属性“借出”。例如，为了记录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。如果您可以提供一些示例代码，我可能会给您一个更有用的答案。