javascript - 使用文档字符串

Question

这是一个新手问题，但我没有设法用谷歌搜索任何关于这个主题的相当简洁但有启发性的内容。我有 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 没有错误，但只生成了虚拟 header 。

Answer 1

当你写这个的时候

function bar (foo) {
    return foo + foo;
}

如果您将光标放在 function 正上方的行中，然后在按下 « Enter » 时写入 /**，您将获得:

/**
 * [bar description]
 * @param  {[type]} foo [description]
 * @return {[type]}     [description]
 */
function bar (foo) {
    return foo + foo;
}

有很多类似的shortcurt。

例如，如果您将光标放在 @param {[type]} foo [description] 之后，按 « Enter » 将创建一个新的 * 行，并编写 @ 将建议您(在智能感知中)所有 JSDoc 注释和验证创建一个完整的行。

当您的文件被正确记录后，只需使用 jsdoc CLI 来创建您的文档。

文档:http://usejsdoc.org/

编辑:我刚刚意识到对您问题的回答在您的 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