You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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(typeofdefine==='function'&&define.amd){define([],function(){returnfactory(atob);});}elseif(typeofexports==='object'){// Shim functions for node.jsfunctionatob(str){returnnewBuffer(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. */functionbase64ToBinaryString(str){returnatob(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. 😦
The text was updated successfully, but these errors were encountered:
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."
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:
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. 😦
The text was updated successfully, but these errors were encountered: