JSDoc'ing写在“显示模块模式”中的Javascript文件的最佳实践样式？ [英] _Best Practices for JSDoc'ing Javascript files written in the "revealing module pattern" Style?
问题描述
我的大部分Javascript函数都比较简单，并且对它们的sideeffect有所帮助：我使用jQuery来操纵DOM或进行Ajax调用。我更喜欢在透露模块模式中写我的功能。
Most of my Javascript functions are relatively simple, and called for their sideeffects: I use jQuery to manipulate the DOM or make Ajax-calls. I prefer to write my functions in the "revealing module pattern" style.
我刚刚发现 JSDoc-注释的Javascript文件有一个好处：帮助的注释，Eclipse的JS开发工具可以解析我的JS文件， 填写Eclipse Outline视图（否则为空）。
I just discovered that JSDoc- annotating Javascript files has a benefit: with the help of the annotations, Eclipse's JS Development Tools can parse my JS file and fill the Eclipse Outline View (which would otherwise be empty).
现在我不知道什么是精细点，或注释的良好做法？我不习惯。
Now I wonder what are the fine points, or the good practices of annotating? I am not used to it.
Google JS风格指南说了一些关于JSDoc的内容：
建议只使用可用标签的一部分，以及其他建议。
The google JS style guide says something about JSDoc: recommends to only use a subset of available tags, among other advice.
现在，我想出了这个模板（此代码没有任何有用的）：
For now, I came up with this template (this code does not do anything useful):
/**
* @fileOverview Say something meaningful about the js file.
* @author <a href="mailto:my@email.net">My name</a>
* @version 1.0.1
*/
/**
* @namespace What the namespace contains or which apps/webpages use it
*/
if (!window['my']['namespace']) {
window['my']['namespace'] = {};
my.namespace = (function() {
/**
* Documentation string...
* @memberOf window.my.namespace
* @private
*/
var clear = function(){};
/**
* Documentation string...
* @memberOf window.my.namespace
* @public
*/
function delete_success(data){
var str = "# of files affected: " + data.length;
$('<pre id="success"/>').html(str).appendTo('#del_0b');
$('<pre id="success"/>').html(data.result).appendTo('#del_sf');
}
//more code
return {
"method1": method1,
"delete_success" : delete_success
};
})(); //my.namespace
} //end if
我应该使用JSDoc标签@function或@memberOf这里，还是两者？
@field标签怎么样？
返回条件是否应该被JSDoc'mented？用哪个标签？
我应该真的不使用@public标签吗？我觉得在这里很有用。
Am I supposed to use JSDoc tag @function or @memberOf here, or both? What about the @field tag? Should the return clause be JSDoc'umented as well? With which tags? Should I really not use the @public tag? I find it useful here.
任何建议？
有没有人知道一个很好的，实用的JSDoc风格的小项目指南？
Any recommendations? Does anyone know a good, practical JSDoc style guide for small projects?
推荐答案
如果您正在寻找代码示例，我发现找到它们的最佳位置在 jsdoc-users Google Group 。我比Google更好运，而且如果您提出问题，他们通常会很有帮助。
If you're looking for code samples, I've found that the best place to find them is in the archives of the jsdoc-users Google Group. I've had much better luck there than searching Google, and if you ask a question they're usually pretty good about helping out.
我不能说Eclipse支持，但是有一个新版本的jsdoc， jsdoc3 。请查看文档 here 。这是一个有点不完整，但我知道他们有更新的书面准备审查，所以他们应该会很快改善。
I can't speak for the Eclipse support, but there is a new version of jsdoc, jsdoc3. Check out the documentation here. It's a little incomplete, but I know they have updates written and ready for review, so they should be improving soon.
关于你的具体问题关于 @function 和 @memberof ，您可能希望使用 @function @memberof 用于简单的功能文档。
Regarding your specific question regarding @function and @memberof, you'll likely want to use @function, not @memberof for simple function documentation.
这篇关于JSDoc'ing写在“显示模块模式”中的Javascript文件的最佳实践样式？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
