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

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

谢谢！

- Jesse Atkinson

---

那是因为JSDoc充满了Java式的语法，不适合JavaScript。最好只编写有意义的注释。 - Raynos

谢谢你，rjmunro。我同意。我并不认为这是太局限了。然而，我已经转向使用Docco进行文档编写。jashkenas.github.com/docco/ - Jesse Atkinson

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...};
}());

- Microfed

---

抱歉，这并没有真正回答我想要做的事情。我已经用更多的信息更新了代码片段。不过还是谢谢你的回复！ - Jesse Atkinson

JavaScript 中没有命名空间。这个结构甚至没有意义。 - Raynos

@Raynos，它们在语言上的区别是什么？它们在jsdoc中。也许从语义上来说并不完全准确，但我所写的是可以工作的。 - Microfed

@Microfed 我觉得它不易读，再说我认为jsdoc是一个肮脏的Java仿真，有太多的结构不适用。 - Raynos

@Raynos，是的，有许多结构不适用。有些结构在内部执行完全相同的操作（例如@arguments和@extends）。你的工作就是使用你认为有用的东西并丢弃其他所有东西。 - Hoffmann

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设置为private和inner以进行描述（因为嵌套函数无法描述）。然后我传入-p来记录私有函数。最后，我添加了一个链接到父函数以供参考。

我认为jsdoc过于挑剔，需要用更好的东西替代它。它是javadoc的移植版，因此有许多与Java相关但不适用于JS的内容，反之亦然。有一些非常常见的JS习惯用法，如闭包或嵌套函数，很难或不可能文档化。

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

- risto

---

你能否也看一下这个链接：https://stackoverflow.com/questions/50330518/jsdocs3-properly-annotate-closure - SumNeuron