javascript 如何使用 jsdoc-toolkit 记录匿名函数（闭包）
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/8071897/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
How to document anonymous functions (closure) with jsdoc-toolkit
提问by Jesse Atkinson
I am trying to document my code using JSDoc-toolkit. My code starts by being wrapped with a self-executing anonymous function. How in the world do I document this? I've spent nearly all day on this. JS Docs will not recognize anything inside of the anonymous function closure due to it not knowing what to do with it. It breaks and none of my comments come through.
我正在尝试使用 JSDoc-toolkit 来记录我的代码。我的代码首先被一个自动执行的匿名函数包装起来。我到底要如何记录这个？我几乎花了一整天的时间在这上面。JS Docs 不会识别匿名函数闭包中的任何内容，因为它不知道如何处理它。它打破了，我的评论都没有通过。
My code looks something like this.
我的代码看起来像这样。
/**
* @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);
}());
Thank you!
谢谢！
回答by Microfed
You can use @namespace with @name and @lends like this:
您可以像这样将@namespace 与@name 和@lends 一起使用：
/**
* @name MyNamespace
* @namespace Hold all functionality
*/
(function () {
"use strict";
/** @lends MyNamespace*/
var stlib = function (param, param, param) { ...All of my code...};
}());
回答by risto
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 checkStringas privateand innerto be descriptive (since nested functions can't be described), And then I pass in -pto document private functions. Finally, I add a link to the parent function for reference.
在这里，我将私有和内部设置checkString为描述性（因为无法描述嵌套函数），然后我传入以记录私有函数。最后，我添加了一个指向父函数的链接以供参考。-p
I think jsdocis 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 closuresor nested functions, that are hard or impossible to document.
我认为这jsdoc是不必要的挑剔，需要用更好的东西代替。它是 的一个端口javadoc，所以它有很多与Java相关但与JS无关的东西，反之亦然。有非常常见的 JS 习语，如闭包或嵌套函数，它们很难或不可能记录。
I always check my namepaths and debug using the --explainflag.
我总是检查我的名称路径并使用该--explain标志进行调试。
