javascript 使用文档字符串
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/34205666/
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
Utilizing docstrings
提问by Alexey Orlov
It's a newbie question, but I didn't manage to google anything reasonably concise yet enlightening on the subject. I've got Sublime Texteditor and an excellent plugin DocBlockrhttps://github.com/spadgos/sublime-jsdocs, which makes proper commenting a piece of cake. What am I supposed to do after I'm through with the comments? At a very minimum, I'd like to be able to invoke annotations in REPL. What else documentation wise is available? I want something lightweight and easy, for medium scripts.
这是一个新手问题，但我没有设法用谷歌搜索任何关于该主题的合理简洁但有启发性的内容。我有Sublime Text编辑器和一个优秀的插件DocBlockrhttps://github.com/spadgos/sublime-jsdocs，这使得正确评论小菜一碟。看完评论后我该怎么办？至少，我希望能够在 REPL 中调用注释。还有什么可用的文档？我想要一些轻量级和简单的东西，用于中等脚本。
EDIT:
编辑：
var helper = exports.helper = (function() {
...
/**
* Reduces a sequence of names to initials.
* @param {String} name Space Delimited sequence of names.
* @param {String} sep A period separating the initials.
* @param {String} trail A period ending the initials.
* @param {String} hyph A hypen separating double names.
* @return {String} Properly formatted initials.
*/
function makeInits(name, sep, trail, hyph) {
function splitBySpace(nm) {
return nm.trim().split(/\s+/).map(function(x) {return x[0]}).join(sep).toUpperCase();
}
return name.split(hyph).map(splitBySpace).join(hyph) + trail;
}
/**
* Reduces a sequence of names to initials.
* @param {String} name Space delimited sequence of names.
* @return {String} Properly formatted initials.
*/
function makeInitials(name) {
return makeInits(name, '.', '.', '-');
}
...
})();
With $ jsdoc src.jsno errors, but only dummy header is generated.
与$ jsdoc src.js没有错误，但只有假头产生。
回答by Bruno Lesieur
When you write this
当你写这个
function bar (foo) {
return foo + foo;
}
If you place your cursor in the line just above functionand you write /**when you push ? Enter ? you'll be obtain this:
如果您将光标放在正上方的行中function并/**在按下时写入？进入 ？你会得到这个：
/**
* [bar description]
* @param {[type]} foo [description]
* @return {[type]} [description]
*/
function bar (foo) {
return foo + foo;
}
There are a lot of similary shortcurt.
有很多类似的捷径。
For exemple, if you place your cursor after @param {[type]} foo [description], push ? Enter ? will create a new a *line, and write @will propose you (in the intellisense) all JSDoc comments and the validation create a full line.
例如，如果您将光标放在 之后@param {[type]} foo [description]，按 ? 进入 ？将创建一个新*行，并且 write@将建议您（在智能感知中）所有 JSDoc 评论和验证创建一个完整的行。
When your file is correctly documented, just use the jsdocCLI to create your documentation.
正确记录您的文件后，只需使用jsdocCLI 创建您的文档。
Documentation: http://usejsdoc.org/
文档：http: //usejsdoc.org/
EDIT: I just realize the response to your question is in your https://github.com/spadgos/sublime-jsdocslink so maybe you want know how generate the documentation so...
编辑：我刚刚意识到对你的问题的回答在你的https://github.com/spadgos/sublime-jsdocs链接中，所以也许你想知道如何生成文档，所以......
Install Node.js and use CLI command
安装 Node.js 并使用 CLI 命令
npm install jsdoc -g
Then, supposed file name you want document is foo.js, run the following command:
然后，假设您想要文档的文件名是foo.js，运行以下命令：
jsdoc foo.js
This will create a documentation into outdirectory.
这将在out目录中创建一个文档。
All CLI documentation to generate doc is here : http://usejsdoc.org/about-commandline.html
生成文档的所有 CLI 文档都在这里：http: //usejsdoc.org/about-commandline.html
回答by Bruno Lesieur
On Global
在全球
To allow JSDoc Template to generate your documentation, you have to add the @functionattribute with the name of your function. Your two functions will appear in Global part of the template.
要允许 JSDoc 模板生成您的文档，您必须添加@function具有函数名称的属性。您的两个函数将出现在模板的全局部分。
jsdoc your-exemple.js
But, because of your function are scoped in an anonymous function (but no module for moment), you do add the @private function to inform that function are not really global but just accessible in its scope. But, because by default JSDoc Generator Template ignore privates functions, add the --privateoptions.
但是，由于您的函数在匿名函数范围内（但暂时没有模块），您确实添加了 @private 函数以通知该函数不是真正的全局函数，而只是在其范围内可访问。但是，因为默认情况下 JSDoc 生成器模板会忽略私有函数，所以添加--private选项。
jsdoc your-exemple.js --private
So your code look like this.
所以你的代码看起来像这样。
(function () {
"use strict";
// ...
/**
* Reduces a sequence of names to initials.
* @function makeInits
* @private
* @param {String} name Space Delimited sequence of names.
* @param {String} sep A period separating the initials.
* @param {String} trail A period ending the initials.
* @param {String} hyph A hypen separating double names.
* @return {String} Properly formatted initials.
*/
function makeInits(name, sep, trail, hyph) {
function splitBySpace(nm) {
return nm.trim().split(/\s+/).map(function (x) { return x[0]; }).join(sep).toUpperCase();
}
return name.split(hyph).map(splitBySpace).join(hyph) + trail;
}
/**
* Reduces a sequence of names to initials.
* @function makeInitials
* @private
* @param {String} name Space delimited sequence of names.
* @return {String} Properly formatted initials.
*/
function makeInitials(name) {
return makeInits(name, '.', '.', '-');
}
// ...
}());
Into Class
走进课堂
If you expose the content of anonymous closure to a variable var Helper, it's possibly a Class. So your code will not be a part of Global content but a part of Class with @classfollowing by class name. And because you will provide your function towards the class module, you have no need to declare function as private.
如果您将匿名闭包的内容暴露给一个变量var Helper，它可能是一个类。所以你的代码不会是全局内容的一部分，而是类的一部分，@class后面跟着类名。并且因为您将向类模块提供您的函数，所以您无需将函数声明为私有。
But you do explain your previous function are part of the class so you have to use @memberOfwith the full path to property.
但是你确实解释了你以前的函数是类的一部分，所以你必须使用@memberOf完整的属性路径。
- Ending by
.if it's a static member (exposed via return). - Ending by
#if it's a method instanciable (exposed via this). - Ending by
~if it's a private function not exposed at all (and@private).
- 通过结束
.，如果它是一个静态成员（通过回暴露）。 - 通过结束
#，如果它是一个方法instanciable（通过此暴露）。 - 通过结束
~，如果它是在所有的（而不是暴露私有函数@private）。
So
所以
/**
* Helper Class
* @Class Helper
*/
var Helper = (function () {
"use strict";
// ...
/**
* Split by Space
* @function privateExemple
* @private
* @memberOf Helper~
* @return {String} ...
*/
function privateExemple() {
return "";
}
/**
* Reduces a sequence of names to initials.
* @function makeInits
* @memberOf Helper.
* @param {String} name Space Delimited sequence of names.
* @param {String} sep A period separating the initials.
* @param {String} trail A period ending the initials.
* @param {String} hyph A hypen separating double names.
* @return {String} Properly formatted initials.
*/
function makeInits(name, sep, trail, hyph) {
function splitBySpace(nm, sep) {
return nm.trim().split(/\s+/).map(function (x) { return x[0]; }).join(sep).toUpperCase();
}
return name.split(hyph).map(splitBySpace).join(hyph) + trail;
}
/**
* Reduces a sequence of names to initials.
* @method makeInitials
* @memberOf Helper#
* @param {String} name Space delimited sequence of names.
* @return {String} Properly formatted initials.
*/
this.makeInitials = function makeInitials(name) {
return makeInits(name, '.', '.', '-');
}
// ...
return {
makeInits: makeInits
};
}());
Into Molule
走进摩尔
But, in your case you use the exportsso that mean your file is a module. So you have to describe this with @moduleand the name. So, all what you have previously comment will be not a part of Global but now a part of your Module. And because you will provide your function behind the Helper module, you have no need to declare function as private.
但是，在您的情况下，您使用的exports是，这意味着您的文件是一个模块。所以你必须用@module名字来描述它。因此，您之前评论的所有内容都不是 Global 的一部分，而是您的 Module 的一部分。因为您将在 Helper 模块后面提供您的函数，所以您无需将函数声明为私有。
/**
* Helper Module
* @module Helper
*/
exports.helper = (function () {
"use strict";
// ...
/**
* Reduces a sequence of names to initials.
* @function makeInits
* @memberOf module:helper.
* @param {String} name Space Delimited sequence of names.
* @param {String} sep A period separating the initials.
* @param {String} trail A period ending the initials.
* @param {String} hyph A hypen separating double names.
* @return {String} Properly formatted initials.
*/
function makeInits(name, sep, trail, hyph) {
function splitBySpace(nm) {
return nm.trim().split(/\s+/).map(function (x) { return x[0]; }).join(sep).toUpperCase();
}
return name.split(hyph).map(splitBySpace).join(hyph) + trail;
}
/**
* Reduces a sequence of names to initials.
* @function makeInitials
* @private
* @memberOf module:helper~
* @param {String} name Space delimited sequence of names.
* @return {String} Properly formatted initials.
*/
function makeInitials(name) {
return makeInits(name, '.', '.', '-');
}
// ...
return {
makeInitials: makeInitials
};
}());
Module and Class
模块和类
But, because you expose via var Helperas a Class and via exportsas a Module you could document in both way.
但是，因为您将 viavar Helper作为 Class 和 viaexports作为 Module公开，所以您可以以两种方式进行记录。
/**
* Helper Class
* @class Helper
* @memberOf module:helper~
* @see {@link module:helper|Module}
*/
var Helper = (function () {
"use strict";
// ...
/**
* Reduces a sequence of names to initials.
* @function makeInits
* @memberOf module:helper.
* @param {String} name Space Delimited sequence of names.
* @param {String} sep A period separating the initials.
* @param {String} trail A period ending the initials.
* @param {String} hyph A hypen separating double names.
* @return {String} Properly formatted initials.
*/
function makeInits(name, sep, trail, hyph) {
function splitBySpace(nm) {
return nm.trim().split(/\s+/).map(function (x) { return x[0]; }).join(sep).toUpperCase();
}
return name.split(hyph).map(splitBySpace).join(hyph) + trail;
}
/**
* Reduces a sequence of names to initials.
* @function makeInitials
* @private
* @memberOf module:helper~
* @param {String} name Space delimited sequence of names.
* @return {String} Properly formatted initials.
*/
function makeInitials(name) {
return makeInits(name, '.', '.', '-');
}
// ...
return {
makeInitials: makeInitials
};
}());
/**
* helper Module
* @module helper
*/
exports.helper = Helper;
Namespace or Class ?
命名空间还是类？
The difference between a Class and a Namespace is just the Class expose some objects/functions via thisand is instanciable. If nothing is attached to this, you have possibly a namespace so just replace @class by @namespace and that code will be placed into appropriate Namespace section.
类和命名空间之间的区别只是类通过公开一些对象/函数this并且是不可实例化的。如果没有附加任何内容，则您可能有一个命名空间，因此只需将 @class 替换为 @namespace，该代码将放入适当的命名空间部分。
You also check if your Class is not an Mixin (just used accross over Class but never directly) or an Interface (defined but not implement) if it an @extend of other class.
您还可以检查您的 Class 是否不是 Mixin（只是在 Class 上使用，但从不直接使用）或接口（已定义但未实现），如果它是其他类的 @extend。
etc.
等等。
See the doc: http://usejsdoc.org/index.html
请参阅文档：http: //usejsdoc.org/index.html
回答by Bruno Lesieur
In your page: https://github.com/Tyrn/js-procr/blob/master/procr/pcn.js
在您的页面中：https: //github.com/Tyrn/js-procr/blob/master/procr/pcn.js
You have the following line:
您有以下行：
if (require.main !== module) return false;
That produce the following error: ERROR. Unable to parse xxx Line 291: Illegal return statement.
这会产生以下错误：ERROR. Unable to parse xxx Line 291: Illegal return statement.
It's because no returnis allowed in global scope so use this insteed:
这是因为return在全局范围内不允许使用 no，所以使用这个 insteed：
if (require.main === module) {
main.copyAlbum();
}
And all your documentation will be produced like a charm.
您的所有文档都将像魅力一样制作。
Actually, I don't know why your jsdoc command produce no errors in your environnent.
实际上，我不知道为什么您的 jsdoc 命令在您的环境中不会产生任何错误。
