28

私は2種類のモジュールを持っています：

Require.jsメインファイル：

    require.config({
      baseUrl: "/another/path",
      paths: {
        "some": "some/v1.0"
      },
      waitSeconds: 15,
      locale: "fr-fr"
    });


    require( ["some/module", "my/module", "a.js", "b.js"],
      function(someModule,    myModule) {
      }
    );

メディエーターパターン：

define([], function(Mediator){

var channels = {};
if (!Mediator) Mediator = {};  

Mediator.subscribe = function (channel, subscription) {   
  if (!channels[channel]) channels[channel] = [];
   channels[channel].push(subscription);
};

Mediator.publish = function (channel) {
  if (!channels[channel]) return;
  var args = [].slice.call(arguments, 1);
  for (var i = 0, l = channels[channel].length; i < l; i++) {
    channels[channel][i].apply(this, args);
  }
};

return Mediator;

});

jsdocでも可能であれば、jsdoc3でこれを文書化するにはどうすればよいですか？

4

5 に答える 5

16

これは SO に関する私の最初の回答です。今後の回答を改善する方法を教えてください。

あなたの具体例

私はこれに対する答えを2日間探していましたが、RequireJS AMDモジュールを冗長性なしで自動的に文書化する方法はないようです(関数名の繰り返しなど)。Karthrik の回答はドキュメントの生成に優れていますが、コード内で名前が変更された場合でも、ドキュメントは jsDoc タグの内容から生成されます。

私がやったことは次のとおりです。これは、Karthikの例から調整されています。@lends1 行目の@nameタグと、jsDoc コメント ブロックからのタグの削除に注意してください。

 define([], /** @lends Mediator */ function(Mediator){
    /** 
     * Mediator class
     * This is the interface class for user related modules
     * @class Mediator
     */

    var channels = {};
    if (!Mediator) Mediator = {};  

    /**
      * .... description goes here ...
      * @function 
      *
      * @param {Number} channel  ..... 
      * @param {String} subscription ..............
      * @example
      * add the sample code here if relevent.
      * 
      */        
    Mediator.subscribe = function (channel, subscription) {   
      if (!channels[channel]) channels[channel] = [];
       channels[channel].push(subscription);
    };

    Mediator.publish = function (channel) {
      if (!channels[channel]) return;
      var args = [].slice.call(arguments, 1);
      for (var i = 0, l = channels[channel].length; i < l; i++) {
        channels[channel][i].apply(this, args);
      }
    };

return Mediator;

});

私が理解していることから、@lendsタグは、次のオブジェクト リテラルからのすべての jsDoc コメントを、@lendsタグによって参照されるクラスの一部として解釈します。この場合、次のオブジェクト リテラルは で始まるものfunction(Mediator) {です。@namejsDoc が関数名などのソース コードを参照できるように、タグが削除されます。

注:@exportsタグを付けた場所と同じ場所でタグを使用しました@lends。それが機能している間、ドキュメントにモジュールが作成されます...そして、クラスのドキュメントを生成したかっただけです。この方法は私のために働く！

一般的な jsDoc リファレンス

于 2013-01-12T12:44:30.923 に答える
9

jsDoc は「define」と「require」の呼び出しを好まないようです。

そのため、複数のタグを使用して jsDoc ツールを作成し、コンストラクターやその他の特定のクラス メソッドを取得することになりました。以下の例を見てください: ソースコードからコピーして貼り付け、クラス名とメソッド名に置き換えました。それがうまくいくことを願っています。

    define([], function(Mediator){
        /** 
         * Mediator class
         * This is the interface class for user related modules
         * @name Mediator
         * @class Mediator
         * @constructor
         * @return Session Object
         */

        var channels = {};
        if (!Mediator) Mediator = {};  

        /**
          * .... description goes here ...
          * @name Mediator#subscribe
          * @function 
          *
          * @param {Number} channel  ..... 
          * @param {String} subscription ..............
          * @example
          * add the sample code here if relevent.
          * 
          */        
        Mediator.subscribe = function (channel, subscription) {   
          if (!channels[channel]) channels[channel] = [];
           channels[channel].push(subscription);
        };

        Mediator.publish = function (channel) {
          if (!channels[channel]) return;
          var args = [].slice.call(arguments, 1);
          for (var i = 0, l = channels[channel].length; i < l; i++) {
            channels[channel][i].apply(this, args);
          }
        };

    return Mediator;

    });

注: 上記の JS コードを文書化する方法は、jsDoc を使用している間はうまくいきました。jsDoc3 を試す機会がありません。

于 2012-04-27T06:22:28.180 に答える
8

Muxa's answer からリンクを取得すると、ドキュメントが特に RequireJS を参照していることがわかります。

RequireJS ライブラリには、モジュール オブジェクトを返す関数を記述できる define メソッドが用意されています。@exports タグを使用して、オブジェクト リテラルのすべてのメンバーをモジュールのメンバーとして文書化する必要があることを文書化します。

モジュールの例

define('my/shirt', function () {
   /** 
    * A module representing a shirt.
    * @exports my/shirt
    * @version 1.0
    */
    var shirt = {

        /** A property of the module. */
        color: "black",

        /** @constructor */
        Turtleneck: function(size) {
            /** A property of the class. */
            this.size = size;
        }
    };

    return shirt;
});

したがって、上記の例では、jsdoc がmy/shirt モジュールcolorを解析し、プロパティとクラスの 2 つのメンバーを持つものとしてドキュメント化することがわかりますTurtleneck。クラスは、Turtleneck独自のプロパティを持つものとしても文書化されますsize。

コンストラクター モジュールの例

@alias タグを使用すると、RequireJS でのコンストラクター モジュールのドキュメント化が簡素化されます。

/** 
 * A module representing a jacket.
 * @module jacket
 */
define('jacket', function () {
    /**
     * @constructor
     * @alias module:jacket
     */
    var exports = function() {
    }

    /** Open and close your Jacket. */
    exports.prototype.zip = function() {
    }

    return exports;
});

上記は、オブジェクトをインスタンス化するクラスとして使用されるモジュールとしてコンストラクター関数をエクスポートする場合に使用したいものです。@lends要約すると、推奨されている およびその他のタグ/テクニックの使用についてはよくわかりません。@module代わりに、 、@exports、およびRequireJS を参照@aliasするドキュメントで使用されているタグに固執しようとします。

requirejs の「メイン」ファイルを文書化する方法がわかりません。私の理解が正しければ、実際にはモジュールを定義しているのではなく、いくつかのモジュールに依存する 1 回限りの関数を実行しています。

于 2013-07-18T00:52:44.417 に答える
2

私の AMD クラスは少し異なる形式を使用していますが、JSDoc もそれらを文書化していませんでした。

グローバル名前空間のコンストラクターは自動的に追加されます。

/**
* @classdesc This class will be documented automatically because it is not in
* another function.
* @constructor
*/
function TestClassGlobal() {
/**
* This is a public method and will be documented automatically.
*/
this.publicMethod = function() {
};
}

AMD モジュール内のコンストラクターでこの動作が必要な場合は、グローバルまたは名前空間のメンバーとして宣言します。

define([], function() {
/**
* @classdesc This won't be automatically documented unless you add memberof,
* because it's inside another function.
* @constructor
* @memberof Namespace
*/
function TestClassNamespace() {
}

/**
* @classdesc This won't be automatically documented unless you add global,
* because it's inside another function.
* @constructor
* @global
*/
function TestClassForcedGlobal() {
}
});
于 2014-02-25T19:43:08.313 に答える