_Best Practices for JSDoc'ing Javascript files written in the "revealing module pattern" Style?

Question

Most of my Javascript functions are relatively simple, and called for their sideeffects: I use jQuery to manipulate the DOM or make Ajax-calls. I prefer to write my functions in the "revealing module pattern" style.

I just discovered that JSDoc- annotating Javascript files has a benefit: with the help of the annotations, Eclipse's JS Development Tools can parse my JS file and fill the Eclipse Outline View (which would otherwise be empty).

Now I wonder what are the fine points, or the good practices of annotating? I am not used to it.

The google JS style guide says something about JSDoc: recommends to only use a subset of available tags, among other advice.

For now, I came up with this template (this code does not do anything useful):

/**
 * @fileOverview Say something meaningful about the js file.
 * @author <a href="mailto:[email protected]">My name</a>
 * @version 1.0.1
 */


/**
 * @namespace What the namespace contains or which apps/webpages use it
 */
if (!window['my']['namespace']) {

    window['my']['namespace'] = {};    
my.namespace = (function() {
    /**
     * Documentation string...
     * @memberOf window.my.namespace
     * @private 
     */
    var clear = function(){};


    /**
     * Documentation string...
     * @memberOf window.my.namespace
     * @public 
     */
    function delete_success(data){
        var str = "# of files affected: " + data.length; 
        $('<pre id="success"/>').html(str).appendTo('#del_0b');
        $('<pre id="success"/>').html(data.result).appendTo('#del_sf');
    }
//more code


  return {
      "method1": method1,
      "delete_success" : delete_success
      };
   })();    //my.namespace
} //end if

Am I supposed to use JSDoc tag @function or @memberOf here, or both? What about the @field tag? Should the return clause be JSDoc'umented as well? With which tags? Should I really not use the @public tag? I find it useful here.

Any recommendations? Does anyone know a good, practical JSDoc style guide for small projects?

Answer 1

If you're looking for code samples, I've found that the best place to find them is in the archives of the jsdoc-users Google Group. I've had much better luck there than searching Google, and if you ask a question they're usually pretty good about helping out.

I can't speak for the Eclipse support, but there is a new version of jsdoc, jsdoc3. Check out the documentation here. It's a little incomplete, but I know they have updates written and ready for review, so they should be improving soon.

Regarding your specific question regarding @function and @memberof, you'll likely want to use @function, not @memberof for simple function documentation.