这是一个新手问题,但我没有设法谷歌任何合理简洁但有启发性的主题。我有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
没有错误,但只生成虚拟标题。
答案 0 :(得分:7)
当你写这个
function bar (foo) {
return foo + foo;
}
如果您将光标放在function
上方的行中,当您按«Enter»时编写/**
,您将获得此信息:
/**
* [bar description]
* @param {[type]} foo [description]
* @return {[type]} [description]
*/
function bar (foo) {
return foo + foo;
}
有很多类似的短篇小说。
例如,如果您将光标放在@param {[type]} foo [description]
之后,按«Enter»将创建一个新的*
行,并写@
将建议您(在intellisense中)所有JSDoc注释和验证创建了一个完整的行。
正确记录文件后,只需使用jsdoc
CLI创建文档。
编辑:我刚刚意识到您的问题的回复位于https://github.com/spadgos/sublime-jsdocs链接中,所以也许您想知道如何生成文档...
安装Node.js并使用CLI命令
npm install jsdoc -g
然后,您想要的文件名是foo.js
,运行以下命令:
jsdoc foo.js
这将在out
目录中创建一个文档。
生成doc的所有CLI文档都在此处:http://usejsdoc.org/about-commandline.html
答案 1 :(得分:1)
全球
要允许JSDoc Template生成文档,您必须添加@function
属性以及您的函数名称。您的两个函数将出现在模板的全局部分中。
jsdoc your-exemple.js
但是,由于你的函数是在一个匿名函数范围内(但暂时没有模块),你确实添加了@private函数来告知该函数不是真正的全局函数,而只是在其范围内可访问。但是,因为默认情况下JSDoc Generator Template会忽略privates函数,所以添加--private
选项。
jsdoc your-exemple.js --private
所以你的代码看起来像这样。
(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, '.', '.', '-');
}
// ...
}());
进入班级
如果将匿名闭包的内容暴露给变量var Helper
,它可能是一个类。因此,您的代码不会成为全局内容的一部分,而是具有@class
类的类的一部分。因为您将为类模块提供函数,所以您无需将函数声明为private。
但是你确实解释了你以前的函数是该类的一部分所以你必须使用@memberOf
和完整的属性路径。
.
是静态成员(通过返回公开),则按#
结束。~
结束,如果它是一种可以实现的方法(通过此方式公开)。@private
完全没有公开的私人功能(和/**
* 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
};
}());
),则按exports
结束。 所以
@module
进入Molule
但是,在您的情况下,您使用/**
* 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
};
}());
,这意味着您的文件是一个模块。因此,您必须使用var Helper
和名称对此进行描述。因此,您之前评论的所有内容都不是Global的一部分,但现在是您的模块的一部分。因为您将在Helper模块后面提供您的功能,所以您无需将函数声明为私有。
exports
模块和类
但是,因为您通过/**
* 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;
作为一个类公开,并通过this
作为模块公开,您可以双向记录。
<script>
var $grid = $("#list2");
emptyMsgDiv = $("<div><span style='color:red; text-align:center;font-size:18px;display:block;'>No Workorder Found</span></div>");
jQuery("#list2").jqGrid({
url:'server.php',
datatype: "json",
mtype: 'POST',
colNames:['WO#','Status','Customer Name','Salesman', 'Created Date', 'WO Total', 'Notes', 'Edit'],
colModel:[
{name:'id',index:'id', align:"center"},
{name:'status1',index:'status1', align:"center", width:100},
{name:'status2',index:'status2', align:"center", width:50},
{name:'status3',index:'status3', align:"center"},
{name:'result',index:'result', align:"center", sortable:false}
],
rowNum:10,
rowList:[10,20,30],
pager: '#pager2',
sortname: 'Invoice.id',
viewrecords: true,
height:'100%',
autowidth:true,
sortorder: "desc",
height: '100%',
loadComplete: function() {
var ts = this;
if (ts.p.reccount === 0) {
$(this).hide();
emptyMsgDiv.show();
} else {
$(this).show();
emptyMsgDiv.hide();
}
}
});
emptyMsgDiv.insertAfter($grid.parent());
</script>
命名空间或类?
Class和Namespace之间的区别就是Class通过<script>
var $grid = $("#list2");
emptyMsgDiv = $("<div><span style='color:red; text-align:center;font-size:18px;display:block;'>No Workorder Found</span></div>");
jQuery("#list2").jqGrid({
url:'server.php',
datatype: "json",
mtype: 'POST',
colNames:['WO#','Status','Customer Name','Salesman', 'Created Date', 'WO Total', 'Notes', 'Edit'],
colModel:[
{name:'id',index:'id', align:"center"},
{name:'status1',index:'status1', align:"center"},
{name:'status2',index:'status2', align:"center"},
{name:'status3',index:'status3', align:"center"},
{name:'result',index:'result', align:"center", sortable:false}
],
rowNum:10,
rowList:[10,20,30],
pager: '#pager2',
sortname: 'Invoice.id',
viewrecords: true,
height:'100%',
sortorder: "desc",
height: '100%',
loadComplete: function() {
var ts = this;
if (ts.p.reccount === 0) {
$(this).hide();
emptyMsgDiv.show();
} else {
$(this).show();
emptyMsgDiv.hide();
}
}
});
emptyMsgDiv.insertAfter($grid.parent());
</script>
公开了一些对象/函数,并且是可以实现的。如果没有附加任何内容,您可能有一个名称空间,所以只需将@class替换为@name,并将该代码放入相应的Namespace部分。
如果它是其他类的@extend,你还要检查你的Class是不是Mixin(只是在跨类使用,但从不直接使用)或接口(已定义但未实现)。
等
答案 2 :(得分:0)
在您的信息页中:https://github.com/Tyrn/js-procr/blob/master/procr/pcn.js
您有以下一行:
if (require.main !== module) return false;
产生以下错误:ERROR. Unable to parse xxx Line 291: Illegal return statement
。
这是因为在全局范围内不允许return
所以请使用此insteed:
if (require.main === module) {
main.copyAlbum();
}
所有文档都会像魅力一样产生。
实际上,我不知道为什么你的jsdoc命令在你的环境中没有产生任何错误。