这是一个新手问题,但我没有设法在谷歌上找到任何关于这个主题的合理简洁而又有启发性的东西。我有Sublime Text
编辑器和一个很好的插件DocBlockr
https://github.com/spadgos/sublime-jsdocs,这使得正确的评论变得易如反掌。在我完成评论之后,我应该做什么?至少,我希望能够在REPL中调用注解。还有什么文档智慧可用?我想要一些轻量级和容易的,为中等脚本。
编辑:
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, '.', '.', '-');
}
...
})();
$ jsdoc src.js
没有错误,但仅生成伪头。
3条答案
按热度按时间46scxncf1#
你写这封信的时候
如果你把你的光标放在
function
的正上方,当你按下回车键时,你会得到这个:有很多相似的捷径。
例如,如果您将光标放在
@param {[type]} foo [description]
之后,按下Enter将创建一个新的*
行,而写入@
将向您建议(在智能意义上)所有JSDoc注解,验证将创建一个完整的行。正确记录文件后,只需使用
jsdoc
CLI创建文档。文件:http://jsdoc.app/
编辑:我刚刚意识到你的问题的答案是在您的https://github.com/spadgos/sublime-jsdocs链接,所以也许你想知道如何生成文档,所以...
安装Node.js并使用CLI命令
然后,假设您希望文档的文件名为
foo.js
,运行以下命令:这将在
out
目录中创建文档。用于生成文档的所有CLI文档都在此处:http://usejsdoc.org/about-commandline.html
ui7jx7zq2#
在全球
要让JSDoc模板生成文档,必须添加
@function
属性和函数名,这两个函数将出现在模板的Global部分。但是,由于函数的作用域是匿名函数(但暂时没有模块),因此需要添加@private函数来通知函数不是真正的全局函数,只是在其作用域中可以访问。但是,由于默认情况下JSDoc生成器模板忽略私有函数,因此需要添加
--private
选项。代码如下所示。
进入课堂
如果你把匿名闭包的内容暴露给一个变量
var Helper
,它可能是一个类。所以你的代码将不是全局内容的一部分,而是类的一部分,@class
后面跟着类名。而且因为你将向类模块提供你的函数,所以你不需要声明函数为private。但您确实解释了之前的函数是类的一部分,因此必须使用
@memberOf
和属性的完整路径。.
结尾(通过return公开)。#
结尾(通过此方法公开)。~
结尾(以及@private
)。所以
变成莫勒
但是,在你的例子中,你使用
exports
,所以这意味着你的文件是一个模块。所以你必须用@module
和名称来描述它。所以,你之前注解的所有内容将不是Global的一部分,而是你模块的一部分。而且因为你将在Helper模块后面提供你的函数,所以你不需要声明函数为private。模块和类
但是,因为您通过
var Helper
作为Class公开,通过exports
作为Module公开,所以可以用两种方式进行文档化。命名空间还是类?
类和命名空间之间的区别只是类通过
this
公开一些对象/函数,并且是可示例化的。如果没有附加任何内容,则可能有一个命名空间,因此只需将@class替换为@namespace,代码将被放置到相应的命名空间部分。你也要检查你的类是否不是一个混合类(只是在类的交叉处使用,但从来没有直接使用过),或者是一个接口(定义了但没有实现),如果它是其他类的@扩展。
等等。
参见文档:http://usejsdoc.org/index.html
xsuvu9jc3#
在您的页面中:https://github.com/Tyrn/js-procr/blob/master/procr/pcn.js
您有以下行:
这会产生以下错误:
ERROR. Unable to parse xxx Line 291: Illegal return statement
.这是因为在全局范围内不允许
return
,所以使用以下替代:你所有的文件都会像符咒一样被制作出来。
实际上,我不知道为什么您的jsdoc命令在您的环境中不产生错误。