Javascript YUIDocs中类和模块的文档

我在为一组分组模块编写文档时遇到了一些问题。我认为这在一定程度上是对

@class

、

@module

和

@namespace

代表什么的误解。（或者，这可能是雅虎试图将“经典”语言词汇塞进JS的结果。）

下面我有一个粗略的示例，展示了我的大部分代码是如何编写的，以及我试图用YUIDoc风格对其进行文档记录。前两部分（

Foo

和

BazManager

）非常简单。对我来说：

• Foo

  是一个

  @类

• Baz

  是一个

  @类

• BazManager

  是一个

  @模块

  （或者可能是一个只包含

  @静态

  成员的

  @类

  ）

• Qux

  也是一个

  @模块

  ，但只包含方法

我的问题是：

如果

BazManager

是

@模块

，则

Foo

显示在

BazManager

下

如果

BazManager

是一个

@class

，那么如果不将

@for

添加到所有内容中，那么

Baz

中的方法就会被卷入其中

如果

BazManager

是一个

@class

，那么记录

Baz

的可见性就变得非常棘手

我真的不知道该如何记录

Qux

。在我看来，它似乎是一个模块，但由于它没有

@class

es，它吞噬了它周围的一切，包括

BazManager

。所以它必须是一个

@类

有人能建议我应该怎么做吗？只要文档中的所有内容都正确生成，我就不在乎这些术语是否正确

以下是我的示例代码：

// 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团队和社区中的许多人（包括我自己）似乎正在远离

@名称空间

。很难做到正确。相反，我们写的类名中有点，即：

@class Plugin.nodemenunan

模块是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

用于扩展其他模块的模块。例如，您可以有一个模块栏，用于向Foo原型添加方法：

/**
Adds extra functionality to Foo

@module Bar
**/

/**
Run really fast

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

---

你试过把这些类放在单独的文件中吗？没有，但我认为文档不应该强制执行项目布局。我开始怀疑，在我的代码中，

MyNamespace

实际上就是模块，

Foo

、

BazManager

和

Qux

都是

@class

是的，我想你的评论就是答案。看看YUI Doc在中对模块的描述：它要求每个源代码树都有一个模块，而且有时并不清楚什么是模块。让MyNameSpace成为模块和名称空间？太好了。谢谢这或多或少就是我最终要做的事情（这是我能让事情准确显示出来的唯一方法）。对于任何遇到这个问题的人来说，

@For

对于一些内部类/构造函数之后的封闭类/构造函数也很有用。如果没有它，这些方法将附加到最后一个内部类。我认为文档中有几个地方提到了这一点，但有些人可能没有立即意识到他们的意思。