利用docstrings

这是一个新手问题，但我没有设法谷歌任何合理简洁，但在这个问题上的启发。 我有Sublime Text编辑器和一个很好的插件DocBlockr https://github.com/spadgos/sublime-jsdocs ，它使适当的评论小菜一碟。 完成评论后，我该怎么做？ 至less，我希望能够在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没有错误，但只生成虚拟头文件。

当你写这个 

 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»将创build一个新的*行，写@将会提示您（在intellisense中）所有的JSDoc注释和validation创build一个完整的行。

当您的文件被正确logging时，只需使用jsdoc CLI来创build文档。

文档： http : //usejsdoc.org/

编辑：我只是意识到你的问题的反应是在你的https://github.com/spadgos/sublime-jsdocs链接，所以也许你想知道如何生成文档，所以…

安装Node.js并使用CLI命令 

 npm install jsdoc -g

然后，假设文件名是foo.js ，运行以下命令： 

 jsdoc foo.js

这将创build一个文件进入out目录。

所有CLI文档生成doc在这里： http : //usejsdoc.org/about-commandline.html

在全球

要允许JSDoc模板生成你的文档，你必须添加@function属性和你的函数的名字。 你的两个函数将出现在模板的Global部分。 

 jsdoc your-exemple.js

但是，由于你的函数被限制在一个匿名函数中（但是暂时没有模块），你可以添加@private函数来通知这个函数并不是全局的，而只是在它的范围内可以访问的。 但是，因为默认JSDoc生成器模板忽略--private函数，添加 – --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, '.', '.', '-'); } // ... }());

入类

如果你将匿名闭包的内容暴露给一个variablesvar Helper ，它可能是一个Class。 因此，您的代码将不会成为全局内容的一部分，而是@class类的一部分，后面是类名称。 而且，因为你将提供你的function对类模块，你不需要声明function为私人。

但是你解释了你以前的function是类的一部分，所以你必须使用@memberOf属性的完整path。

  • 结束. 如果它是一个静态成员（通过返回公开）。
  • 如果这是一个方法instanciable（通过这个暴露）结束# 。
  • 如果它是一个私有函数（和@private ）， @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 }; }());

入Molule

但是，在你的情况下，你使用exports ，这意味着你的文件是一个模块。 所以你必须用@module和名字来描述这个。 所以，你以前评论过的所有内容都不是Global的一部分，但现在是你的模块的一部分。 而且因为你将会在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 }; }());

模块和类

但是，因为您通过var Helper作为Class公开，并且通过exports作为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;

命名空间或类？

Class和Namespace之间的区别只是通过this类暴露了一些对象/函数，并且是可以实现的。 如果没有附加到这个，你可能有一个名称空间，所以只需要@namespacereplace@class，该代码将被放置到适当的命名空间部分。

你还要检查你的类是不是一个Mixin（只是跨过Class而不是直接使用）或者一个接口（定义但不是实现），如果它是其他类的@extend。

等等

请参阅文档： http ： //usejsdoc.org/index.html

在你的页面中： 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 ERROR. Unable to parse xxx Line 291: Illegal return statement 。

这是因为在全球范围内不允许任何return ，所以使用这个保证： 

 if (require.main === module) { main.copyAlbum(); }

而且所有的文档都会像魅力一样产生。

其实，我不知道为什么你的jsdoc命令在你的环境中不会产生任何错误。

Interesting Posts