Question

感谢此处的回答：

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

我的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没有类。不是那种被称为“类”的命名法。在阅读文档时，它会创建一个奇怪的断开连接以查看“类”列表。
自动添加“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');

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

/** 
* 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的东西的想法。如果你能提供一些示例代码，我可以给你一个更有用的答案。

JSDoc

1 个答案: