我在为一组分组模块编写文档时遇到了一些麻烦。我认为这在一定程度上是对 @class、@module 和 @namespace 代表什么的误解。 (或者这可能是雅虎试图将“经典”语言词汇硬塞进 JS 的结果。)

我在下面有一个粗略的示例，显示了我的大部分代码是如何编写的，以及我尝试以 YUIDoc 风格记录它。前两部分(Foo 和 BazManager)非常简单。对我来说:

• Foo 是一个@class；
• Baz 是一个@class；
• BazManager 是一个@module(或者可能是一个只包含@static 成员的@class)；
• Qux 也是一个 @module 但只包含方法。

我的问题是:

1. 如果 BazManager 是一个 @module，Foo 会出现在 BazManager 下；
2. 如果 BazManager 是一个 @class，如果您不添加 @for，Baz 中的方法就会被吸入其中 一切;
3. 如果 BazManager 是一个 @class，那么记录 Baz 的可见性就变得非常棘手；
4. 我真的不知道我应该如何记录Qux。在我看来它是一个模块，但由于它没有 @classes，它吞噬了周围的一切，包括 BazManager。所以它必须是一个@class。

谁能建议我应该怎么做？只要文档中的所有内容都能正确生成，我真的不在乎我是否正确使用了这些条款。

这是我的示例代码:

// File: Widgets.js

/**
MyNamespace namespace
@namespace MyNamespace
*/
var MyNamespace = window.MyNamespace || {};

//--------------------PART 1: Foo-------------------//

/**
This is a description of Foo.
@class Foo
*/
MyNamespace.Foo = function () {
    this.toString = function () {
        return "I am a foo";
    };

    /**
    This is Foo's private method description.
    @method privateMethod
    @private
    */
    var privateMethod = function () {};

    /**
    This is Foo's public method description.
    @method publicMethod
    */
    this.publicMethod = function () {};
};


//--------------------PART 2: Baz-------------------//
/**
This is a description of BazManager.
@module BazManager
@namespace MyNamespace
*/
MyNamespace.BazManager = (function () {
    var self = {};

    /**
    This is a description of Baz.
    @class Baz
    */
    var Baz = function (type) {
        /**
        toString description
        @method toString
        @returns {String}
        */
        this.toString = function () {
            return "I am a baz and I'm " + type;
        };
    };

    /**
    This is BazManager's privateBaz description.
    @method privateBaz
    @private
    */
    var privateBaz = new Baz("private");

    /**
    This is BazManager's publicBaz description.
    @method publicBaz
    */
    self.publicBaz = new Baz("public");

    return self;
} ());


//--------------------PART 3: Qux-------------------//

MyNamespace.Qux = (function () {
    var self = {};
    /**
    execute description
    @method execute
    @private
    */
    var execute = function () {
        console.log("Qux is done");
    };

    /**
    start description
    @method start
    */
    self.start = function () {
        setTimeout(execute, 1000);
    };

    return self;
} ());

最佳答案

在 YUIDoc 中，@class 用于经典类和包含大量方法的对象。要实例化的类也用 @constructor 标记。这主要是因为这些类随后在模板中显示的方式。与许多单独的函数相比，跟踪一个类要容易得多。

YUI 团队和社区中的许多人(包括我自己)似乎正在远离 @namespace。很难做到正确。相反，我们正在编写带有点的类名，即:@class Plugin.NodeMenuNav。

模块是 YUI 意义上的意思，通常可以理解为包含一个或多个类的“脚本”。

所以一个典型的模块看起来像这样:

/**
A series of utilities to do stuff

@module Stuff
**/

/**
A class that does foo very well

@class Foo
@constructor
@param {Object} [config] Configuration object
@param {Boolean} [config.jumpHigh] Whether foo should jump really high
**/
function Foo(config) {
  config = config || {};
  var high = config.jumpHigh;
}
/**
@method jump
@chainable
**/
Foo.prototype.jump = function () {
    // jump
    return this;
};

/**
A series of utilities to make Foo do more stuff

@class FooUtils
**/
var FooUtils = {
    /**
    @method doSomeStuff
    @static
    **/
    doSomeStuff: function () {

    }
};

最后，@for 用于扩展其他模块的模块。例如，您可以有一个模块 Bar，它向 Foo 的原型(prototype)添加方法:

/**
Adds extra functionality to Foo

@module Bar
**/

/**
Run really fast

@method run
@for Foo
**/
Foo.prototype.run = function () {};bv

关于javascript - YUIDocs 中类和模块的文档，我们在Stack Overflow上找到一个类似的问题： https://stackoverflow.com/questions/13876554/