Utilizing docstrings

Question

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.

EDIT:

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, '.', '.', '-');
  }

...

})();

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

Answer 1

When you write this

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

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;
}

There are a lot of similary shortcurt.

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.

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

Documentation: http://usejsdoc.org/

EDIT: 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...

Install Node.js and use CLI command

npm install jsdoc -g

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

jsdoc foo.js

This will create a documentation into out directory.

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