Question

I have a JavaScript singleton object created with closure method:

/**
 * This is the singleton.
 *
 * @namespace window.Something.Singleton
 */
window.Something.Singleton = (function() {
  /**
   * Foo method.
   *
   * @return {String} this method always returns with <code>bar</code>
   */
  function _foo() { return "bar"; }

  /**
   * @lends window.Something.Singleton#
   */
  return {
    /**
     * @borrows window.Something-_foo
     * @function
     */
    foo: _foo
  };
}());

But the jsdoc-toolkit does not generate the inherited documentation from _foo method to the foo method what I would like to have.

If I write @see instead of @borrows it works (inserts a link to the correct method), but I don’t want to copy&paste the documentation for the foo method to have a public documentation as well.

Answer 1

I did some tests, and I have good news and bad news :). The good news is that it looks like you can get this to work by putting the @borrows tag in the Singleton doc comment:

/**
 * This is the singleton.
 *
 * @namespace Something.Singleton
 * @borrows Something.Singleton-_foo as foo
 */
Something.Singleton = (function() {
   // etc
})());

But this has several ramifications, good and bad:

• The foo function is marked static. This is probably a good thing, as it seems to be accurate as I understand your code.
• With the code as it is currently shown (i.e. no more methods on the singleton, etc), you can dispense with the @lends tag entirely, unless you want to include it for clarity. If all methods are listed as @borrows on the top singleton namespace, then you don’t need to further document them in the returned object. Again, this is probably a good thing.
• The bad news is that I couldn’t get this to work unless the borrowed method was explicitly marked @public – which makes it show up, redundantly, in the documentation. I think this is unavoidable – if jsdoc-toolkit thinks the method is private, it won’t create documentation, so you can’t refer to it (I get WARNING: Can't borrow undocumented Something.Singleton-_foo.). If the method is public, it gets displayed in the documentation.

So this works:

/**
 * This is the singleton.
 *
 * @namespace Something.Singleton
 * @borrows Something.Singleton-_foo as foo
 */
Something.Singleton = (function() {
  /**
   * @public
   * Foo method.
   *
   * @return {String} this method always returns with <code>bar</code>
   */
  function _foo() { return "bar"; }

  return {
    foo: _foo
  };
}());

…in that it copies the documentation for _foo to foo, but it will display _foo in the documentation page as well:

Method Summary
<inner>  _foo()
<static>  Something.Singleton.foo()

Probably the best workaround is simply to forget @borrows entirely and explicitly name _foo as Something.Singleton.foo in the doc comment, marking it as a public function (you could dispense with @public if you didn’t name your inner function with an underscore, but this tells jsdoc-toolkit to treat it as private unless told otherwise):

/**
 * This is the singleton.
 *
 * @namespace Something.Singleton
 */
Something.Singleton = (function() {
  /**
   * @name Something.Singleton#foo
   * @public
   * @function
   * Foo method.
   *
   * @return {String} this method always returns with <code>bar</code>
   */
  function _foo() { return "bar"; }

  return {
    foo: _foo
  };
}());

This will produce the code documentation you’re looking for, and puts the comment next to the actual code it relates to. It doesn’t fully satisfy one’s need to have the computer do all the work – you have to be very explicit in the comment – but I think it’s just as clear, if not more so, than what you had originally, and I don’t think it’s much more maintenance (even in your original example, you’d have to change all your doc comments if you renamed Something.Singleton).