如何使用jsdoc 3或jsdoc记录Require.js（AMD）模块？ [英] How to document a Require.js (AMD) Modul with jsdoc 3 or jsdoc?

问题描述

我有两种类型的模块：

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记录这个？

How can i document this with jsdoc3 when possible with jsdoc too?

推荐答案

这是我在SO上的第一个答案，请让我知道如何改进未来的答案。

我一直在寻找一个好的两天的答案，而且似乎没有一种自动记录RequireJS AMD模块的方法，没有一些冗余（如重复的函数名称）。 Karthrik的答案很好地生成了文档，但是如果在代码中重命名某些内容，文档仍然会从jsDoc标记中的内容生成。

I've been searching for an answer for this for a good two days, and there doesn't seem to be a way to document RequireJS AMD modules automatically without some redundancy (like repeated function names). Karthrik's answer does a good job of generating the documentation, but if something gets renamed in the code the documentation will still be generated from what's in the jsDoc tags.

我结束了什么从Karthik的例子中可以调整以下内容。请注意第1行的 @lends 标记，以及从jsDoc注释块中删除 @name 标记。 / p>

What I ended up doing is the following, which is adjusted from Karthik's example. Note the @lends tag on line 1, and the removal of the @name tag from the jsDoc comment blocks.

 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 tag将解释来自下一个对象文字的所有jsDoc注释，作为 @lends 标记引用的类的一部分。在这种情况下，下一个对象文字是以函数（Mediator）{开头的文字。删除 @name 标记，以便jsDoc在源代码中查找函数名称等。

From what I understand, the @lends tag will interpret all jsDoc comments from the next following object literal as part of the class referenced by the @lends tag. In this case the next object literal is the one beginning with function(Mediator) {. The @name tag is removed so that jsDoc looks in the source code for function names, etc.

注意：我在 @lends 标记的同一位置使用了 @exports 标记。虽然这有效，但它会在文档中创建一个模块......我只想为该类生成文档。这种方式适合我！

Note: I've used the @exports tag at the same place as where I put the @lends tag. While that works, it'll create a module in the docs… and I only wanted to generate docs for the class. This way works for me!

• jsdoc-toolkit标记参考 - jsdoc-toolkit中标记的很好参考。也有很多例子！


• 2ality的jsDoc介绍 - 基于jsDoc-toolkit的综合教程。


• jsDoc3 reference - 相当不完整，但有一些例子。

• jsdoc-toolkit Tag Reference - Great reference for the tags in jsdoc-toolkit. Has a bunch of examples, too!
• 2ality's jsDoc intro - Comprehensive tutorial based on jsDoc-toolkit.
• jsDoc3 reference - Fairly incomplete, but has some examples.

这篇关于如何使用jsdoc 3或jsdoc记录Require.js（AMD）模块？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！