如何使用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的例子进行调整的.请注意第@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) {.该@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其他标签/技术.相反,我会尽量坚持使用@module,@exports以及@alias在使用标签文件引用RequireJS.

我不确定你应该如何记录你的requirejs'main'文件.如果我理解正确,你实际上并没有在那里定义任何模块,而是执行依赖于几个模块的一次性函数.