27

感谢在这里找到的答案：

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 没有那种意义上的类。不是那些被称为“类”的命名法。在阅读文档以查看“类”列表时，它会产生奇怪的断开连接。

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

[编辑：示例代码]

所以这是当前的结构。在我用 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! }
}
4

1 回答 1

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

于 2015-06-18T21:14:23.890 回答