35

我正在尝试使用 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);
 }());

谢谢！

4

2 回答 2

4

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

/**
* @name MyNamespace
* @namespace Hold all functionality
*/
(function () {
    "use strict";
    /** @lends MyNamespace*/
    var stlib = function (param, param, param) { ...All of my code...};
}());
于 2011-11-09T21:58:27.837 回答
3

You can't document nested functions directly. But you can do something like this:

/**
 * @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'));

Here I'm setting checkString as private and inner to be descriptive (since nested functions can't be described), And then I pass in -p to document private functions. Finally, I add a link to the parent function for reference.

I think jsdoc is unnecessarily finicky and needs to be replaced with something better. It's a port of javadoc, so it has a lot of things that are relevant to Java but not JS, and vice versa. There are very common JS idioms, like closures or nested functions, that are hard or impossible to document.

I always check my namepaths and debug using the --explain flag.

于 2014-12-17T02:11:56.290 回答