_best Practices For Jsdoc'ing Javascript Files Written In The "revealing Module Pattern" Style?

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

Solution 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.

Solution 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).

Solution 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

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.