8

グループ化されたモジュールのセットのドキュメントを作成するのに少し問題があります。私はそれが何を表しているのかについての誤解の一部だと@class思います@module。@namespace（あるいは、Yahooが「古典的な」言語の語彙をJSに押し込もうとした結果かもしれません。）

以下に、コードの大部分がどのように記述されているか、およびYUIDocスタイルでそれを文書化する試みを示す大まかなサンプルを示します。最初の2つの部分（FooおよびBazManager）は非常に単純です。私に：

  • Fooです@class;
  • Bazです@class;
  • BazManagerは@module（またはメンバー@classのみを含む）です。@static
  • Quxもですが、@moduleメソッドのみが含まれています。

私の問題は次のとおりです。

  1. の場合、BazManagerは;の下@moduleに表示されます。FooBazManager
  2. の場合BazManager、すべてに追加しないと@class、内部のメソッドがBazそれに吸い込まれます。@for
  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;
} ());
4

1 に答える 1

9

YUIDocでは@class、従来のクラスと一連のメソッドを含むオブジェクトの両方に使用されます。インスタンス化されることを意図したクラスも。でマークされ@constructorます。これは主に、これらのクラスがテンプレートに表示される方法が原因です。多くの単独の関数よりも、クラスを追跡する方がはるかに簡単です。

YUIチームとコミュニティの多くの人（私自身を含む）はから離れているようです@namespace。正しく理解するのは難しいです。代わりに、ドットを含むクラス名を記述しています。つまり、次のようになります@class Plugin.NodeMenuNav。

モジュールはYUIの意味で意味され、ほとんどの場合、1つ以上のクラスを含む「スクリプト」として理解できます。

したがって、一般的なモジュールは次のようになります。

/**
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のプロトタイプにメソッドを追加するモジュールBarを作成できます。

/**
Adds extra functionality to Foo

@module Bar
**/

/**
Run really fast

@method run
@for Foo
**/
Foo.prototype.run = function () {};bv
于 2012-12-20T15:32:12.643 に答える