35

I am trying to document my code using JSDoc-toolkit. My code starts by being wrapped with a self-executing anonymous function. How in the world do I document this? I've spent nearly all day on this. JS Docs will not recognize anything inside of the anonymous function closure due to it not knowing what to do with it. It breaks and none of my comments come through.

My code looks something like this. 

/** 
 * @fileoverview BLA BLA BLA
 */

/**
 * This is where I don't know what to put.
 */
 (function () {
     "use strict";

     /** or here */
     var stlib = function (param, param, param) {
         /** or here */
         var share = {
             /** or here */
             config: {
                 button: DOM Element,
                 property: blablabla
             },

             init: function () { ...some init code here}
         };

         share.init();
     };

     widgets.add("share", stlib);
 }());

Thank you!

Jesse Atkinson
  • 8,386
  • 12
  • 38
  • 44
  • That's because JSDoc is fully of java-isms and doesn't fit to JavaScript. Just write sensible comments instead – Raynos Nov 10 '11 at 05:34
  • Thank you, rjmunro. I agree. I didn't think it was too localized at all. I have, however, switched to Docco for documentation since. jashkenas.github.com/docco/ – Jesse Atkinson May 31 '12 at 20:43

2 Answers2

4

You can use @namespace with @name and @lends like this:

/**
* @name MyNamespace
* @namespace Hold all functionality
*/
(function () {
    "use strict";
    /** @lends MyNamespace*/
    var stlib = function (param, param, param) { ...All of my code...};
}());
Microfed
  • 2,432
  • 19
  • 25
  • My apologies. This didn't really answer what I was trying to do. I updated the code snippet with more information. Thank you for your reply though! – Jesse Atkinson Nov 10 '11 at 05:10
  • There are no namespaces in javascript. The construct doesn't even make sense – Raynos Nov 10 '11 at 05:35
  • 3
    @Raynos What is the difference that they are not in the language? They are [in](http://code.google.com/p/jsdoc-toolkit/wiki/TagNamespace) jsdoc. Maybe it's not really true of semantics, but what I wrote, it works. – Microfed Nov 10 '11 at 06:29
  • 1
    @Microfed I don't find it readable then again I find jsdoc a dirty java emulation with too many constructs that just don't apply – Raynos Nov 10 '11 at 13:10
  • @Raynos yes there are many constructs that do not apply. Many that do exactly the same thing internally (@ aguments and @ extends for example). It's your job to use what you think will be useful and discard everything else. – Hoffmann Nov 27 '12 at 13:18
3

You can't document nested functions directly. But you can do something like this:

/**
 * @module foobar
 */

/**
* @function
* @author Baa
* @name hello 
* @description Output a greeting
* @param {String} name - The name of the person to say hello
*/
(function hello(name) {
    /**
     * @function
     * @author Baz
     * @inner
     * @private
     * @memberof module:foobar
     * @description Check if the argument is a string (see: {@link module:foobar~hello})
     * @param {String} string - The string
     * @returns {String} Returns true if string is valid, false otherwise
     */ 
    var isString = function checkString(string) { return typeof string === 'string'; };
    if (isString(name))
      console.log('Hello ' + name + '!');
}('Mr. Bubbles'));

Here I'm setting checkString as private and inner to be descriptive (since nested functions can't be described), And then I pass in -p to document private functions. Finally, I add a link to the parent function for reference.

I think jsdoc is unnecessarily finicky and needs to be replaced with something better. It's a port of javadoc, so it has a lot of things that are relevant to Java but not JS, and vice versa. There are very common JS idioms, like closures or nested functions, that are hard or impossible to document.

I always check my namepaths and debug using the --explain flag.

risto
  • 1,204
  • 8
  • 11
  • could you maybe also check out https://stackoverflow.com/questions/50330518/jsdocs3-properly-annotate-closure – SumNeuron May 16 '18 at 19:37