_Best Practices for JSDoc'ing Javascript files written in the “revealing module pattern” Style? [closed]

问题

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:my@email.net">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?

回答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.

回答2:

In Eclipse @memberOf (with capital O) does the trick for the outline (Ctrl+O shortcut). I use JSDoc mostly for the Eclipse outline, but I also use @author for humans :)

I also use @private on private functions.

IMHO JSDT is OK but not very helpful, it did not evolve much lately. You should use an Eclipse JSHint plugin or use TypeScript with an Eclipse plugin (you can do refactoring but adds some complexity).

回答3:

for me (Eclipse 4.3 Kepler) the following works fine:

my.namespace.foo.AbstractClass = {

  /** @memberOf my.namespace.foo.StaticClass  <- this statement already 
   *                   fixes the Eclipse Outline and Package Views for all other members
   */
  staticMethod1 : function() { /* ... */ },

  /** no need to add some JSDoc here for the Outline etc. */
  staticMethod2 : function() { /* ... */ }
}

(for "non-abstract" classes, speaking Java, it should be similar)

which is nice because:

it's almost the minimum to not repeat the namespace or JSDoc tags all over
I do not have to fiddle around with prototype or this
the "abstract class"¹ is immediately created

^1: I know - everything is object - but I feel better with stronger typed and namespaced environments/clearer/more defined concepts like in Java. The whole JavaScript stuff is just grown and (IMHO) really bad and hard to work with in bigger environments with multiple programmers and solid refactoring support, good maintainability, testability, modularity, dependency management, self documentation etc.

来源：https://stackoverflow.com/questions/12838536/best-practices-for-jsdocing-javascript-files-written-in-the-revealing-module

标签

javascript

eclipse

documentation

documentation-generation

jsdoc