Improve support for UMD module documentation

[jcranmer]

Having attempted to get JSDoc to document my modules, the results are, quite frankly, atrocious, without excessively verbose and repetitive annotation of documentation comments. This really destroys part of the purpose of documentation--I partially want to make sure via automatic generation that none of my code is undocumented, and if the documentation requires adding lots of notes just to get JSDoc to tell that it exists, then it's a problem.

Here is a pared-down example of the code I'm trying to document:

/**
 * This module contains a bunch of utilities for SASL implementers, partially
 * to help bridge differences between Node.js and web browsers.
 * @module sasl-utils
 */
(function (root, factory) {
  if (typeof define === 'function' && define.amd) {
    define([], function () { return factory(atob); });
  } else if (typeof exports === 'object') {
    // Shim functions for node.js
    function atob(str) {
      return new Buffer(str, "base64").toString("binary");
    }
    module.exports = factory(atob);
  } else {
    root.saslUtils = factory(atob);
  }
}(this, function (atob) {
/**
 * Convert a string containing base64-encoded data into a Uint8Array containing
 * that data.
 *
 * @param {String} str The base64-encoded string.
 * @returns {String}   The resulting base64-decoded string.
 */
function base64ToBinaryString(str) {
  return atob(str);
}

return {
  base64ToBinaryString: base64ToBinaryString,
};
}));

I've tried many methods to figure out how to get the return value registered, such as using putting /** @alias module:sasl-utils */ in many strategic places, but at no point could I get documentation to be detected except by adding /** @alias module:sasl-utils.base64ToBinaryString */ or similar code to every single function.

Now I'm not exactly an irate user who is complaining without proposing a fix. I've done enough debugging of the issue that I've identified that the key issue is that the documentation for the functions is being parsed as "<anonymous>~base64ToBinaryString" and there is a correct "module:sasl-utils.base64ToBinaryString" being generated--but the correct one being generated is happening at the object literal in the return statement, which is not identified as referring to the function that's getting the anonymous tag. Therefore, the declaration in the returned object literal is dropped as undocumented and the documented declaration is dropped as being anonymous.

Unfortunately, even though I've poked the code enough to figure out that this is happening, I haven't figured out how to fix the object literal to merge the two declarations together. 😦

[hegemonic]

I don't have a better solution for you than using the @alias tag. If you can't live with that, you'll have to find a less "atrocious" tool that doesn't "destroy" your documentation and leave you feeling "irate."

[jcranmer]

So you are completely against my suggestion in the last paragraph of merging the documentation tags based on the returned object literal?