利用docstrings [英] Utilizing docstrings

问题描述

这是一个新手问题，但我没有设法谷歌任何合理简洁但有启发性的主题。我有 Sublime Text 编辑器和一个优秀的插件 DocBlockr https://github.com/spadgos/sublime-jsdocs ，这使得正确评论变得轻而易举。在完成评论后我该怎么做？至少，我希望能够在REPL中调用注释。还有哪些文档明智？对于中等脚本，我想要轻量级和简单的东西。

It's a newbie question, but I didn't manage to google anything reasonably concise yet enlightening on the subject. I've got Sublime Text editor and an excellent plugin DocBlockr https://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.

编辑：

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 没有错误，但只生成虚拟标题。

With $ jsdoc src.js no errors, but only dummy header is generated.

推荐答案

当你写这个

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

如果将光标放在上方的行中函数并且当你按«Enter»时你写 / ** 你会得到这个：

If you place your cursor in the line just above function and you write /** when you push « Enter » you'll be obtain this:

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

有很多类似的短片。

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

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.

正确记录文件后，只需使用 jsdoc CLI创建文档。

When your file is correctly documented, just use the jsdoc CLI to create your documentation.

文档： http://usejsdoc.org/

编辑：我刚刚意识到你的问题的答案在你的 https： //github.com/spadgos/sublime-jsdocs 链接所以也许你想知道如何生成文档...

I just realize the response to your question is in your https://github.com/spadgos/sublime-jsdocs link so maybe you want know how generate the documentation so...

安装Node.js并使用CLI命令

Install Node.js and use CLI command

npm install jsdoc -g

n，你想要文件的假定文件名是 foo.js ，运行以下命令：

Then, supposed file name you want document is foo.js, run the following command:

jsdoc foo.js

这将创建的文档out 目录。

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

All CLI documentation to generate doc is here : http://usejsdoc.org/about-commandline.html

这篇关于利用docstrings的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！