如何使用jsdoc 3或jsdoc記錄Require.js（AMD）模塊？

Question

我有兩種類型的模塊：

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;

});

如果可能的話，我怎么能用jsdoc3記錄這個？

Answer 1

這是我在SO上的第一個答案，請讓我知道如何改進未來的答案。

你的具體例子

我一直在尋找一個好的兩天的答案，並且似乎沒有辦法自動記錄RequireJS AMD模塊而沒有一些冗余（如重復的函數名稱）。 Karthrik的答案很好地生成了文檔，但是如果在代碼中重命名了某些內容，那么仍然會從jsDoc標記中的內容生成文檔。

我最終做的是以下內容，這是根據Karthik的例子進行調整的。 注意第1行的@lends標記，以及從jsDoc注釋塊中刪除@name標記。

 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) {開頭的文字。 刪除@name標記，以便jsDoc在源代碼中查找函數名稱等。

注意：我在@exports標記的同一位置使用了@lends標記。 雖然這有效，但它會在文檔中創建一個模塊......我只想為該類生成文檔。 這種方式適合我！

一般jsDoc參考

• jsdoc-toolkit標記參考 - jsdoc-toolkit中標記的很好的參考。 還有一堆例子！
• 2ality的jsDoc介紹 - 基於jsDoc-toolkit的綜合教程。
• jsDoc3參考 - 相當不完整，但有一些例子。

Answer 2

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;

    });

注意：使用jsDoc時，上面記錄JS代碼的方法對我們來說效果很好。 沒有機會嘗試jsDoc3。

Answer 3

從Muxa的答案中獲取鏈接 ，我們看到文檔特別提到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 ，以及類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和其他標簽/技術。 相反，我會嘗試堅持引用RequireJS的文檔中使用的@module ， @exports和@alias標記。

我不確定你應該如何記錄你的requirejs'main'文件。 如果我理解正確，你實際上並沒有在那里定義任何模塊，而是執行依賴於幾個模塊的一次性函數。

Answer 4

我的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() {
}
});

Answer 5

看起來JSDoc3中的事情變得更加簡單了。 以下對我有用：

Mediator作為一個模塊

/**
 * Mediator Module
 * @module Package/Mediator
 */
define([], function(Mediator){

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

  /**
   * Subscribe
   * @param  {String} channel Channel to listen to
   * @param  {Function} subscription Callback when channel updates
   * @memberOf module:Package/Mediator
   */
  Mediator.subscribe = function (channel, subscription) {   
    if (!channels[channel]) channels[channel] = [];
     channels[channel].push(subscription);
  };

  /**
   * Publish
   * @param  {String} channel  Channel that has new content
   * @memberOf module:Package/Mediator
   */
  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;

});

但是，我可能會對代碼進行以下更改：

/**
 * Mediator Module
 * @module Package/Mediator
 */
define([], function(){

  var channels = {};
  var Mediator = {}

  ...

原因是，模塊說它定義了Mediator ，但似乎是從Mediator其他一些實例借用的。 我不確定我明白這一點。 在這個版本中，很明顯Mediator是由這個文件定義並導出的。