Question

我正在尝试使用JSDoc-toolkit记录我的代码。我的代码首先包含一个自执行的匿名函数。我怎么在世界上记录这个？我几乎整天都在这上面。 JS Docs不会识别匿名函数闭包内部的任何内容，因为它不知道如何处理它。它打破了，我的评论都没有通过。

我的代码看起来像这样。

/** 
 * @fileoverview BLA BLA BLA
 */

/**
 * This is where I don't know what to put.
 */
 (function () {
     "use strict";

     /** or here */
     var stlib = function (param, param, param) {
         /** or here */
         var share = {
             /** or here */
             config: {
                 button: DOM Element,
                 property: blablabla
             },

             init: function () { ...some init code here}
         };

         share.init();
     };

     widgets.add("share", stlib);
 }());

谢谢！

Answer 1

您可以将@namespace与@name和@lends一起使用，如下所示：

/**
* @name MyNamespace
* @namespace Hold all functionality
*/
(function () {
    "use strict";
    /** @lends MyNamespace*/
    var stlib = function (param, param, param) { ...All of my code...};
}());

Answer 2

您无法直接记录嵌套函数。但你可以这样做：

/**
 * @module foobar
 */

/**
* @function
* @author Baa
* @name hello 
* @description Output a greeting
* @param {String} name - The name of the person to say hello
*/
(function hello(name) {
    /**
     * @function
     * @author Baz
     * @inner
     * @private
     * @memberof module:foobar
     * @description Check if the argument is a string (see: {@link module:foobar~hello})
     * @param {String} string - The string
     * @returns {String} Returns true if string is valid, false otherwise
     */ 
    var isString = function checkString(string) { return typeof string === 'string'; };
    if (isString(name))
      console.log('Hello ' + name + '!');
}('Mr. Bubbles'));

我将checkString设置为私有和内部是描述性的（因为无法描述嵌套函数），并且然后我传入-p来记录私人功能。最后，我添加一个指向父函数的链接以供参考。

我认为jsdoc不必要地挑剔，需要用更好的东西代替。它是javadoc的端口，所以它有许多与Java相关但不与JS相关的东西，反之亦然。有很常见的JS习语，比如 closures 或嵌套函数，很难或无法记录。

我总是检查我的名称路径并使用--explain标志进行调试。

如何使用jsdoc-toolkit记录匿名函数（闭包）

2 个答案: