How do you document anonymous functions ?

Question

I'm specifically referring to JavaScript anonymous function but this could be relevant to other languages. I like to use JSDoc notations in my scripts because I know other people will be hacking at it sooner or later. When i have pretty complex anonymous function how do people document it so that it gets picked up by Eclipse and other IDE's that understand JSDoc or JavaDoc notations?

/**
 * Blah Blah blah
 *
 * @param Object Blah blah blah
 * @return Blah Blah Blah
 * @type Object
 */
function foo(this) {
......
this.bar = function () { ... complex code .....};
......
return obj;
}

Thanks

Answer 1

By making it not anonymous.

I find the best way to document something is to not to. What I mean I I use good variable/function names and clear code as my document.

So in this case I would just create a static function that creates that anonymous and thus I can give that static function a good name.it

Answer 2

Ideally an anonymous function should be short and perform a straightforward task. So... the outer function that contains it should provide sufficient documentation.

If that is not the case you should likely extract the anonymous function out into a named function, and then properly document it.

Answer 3

This is not really an anonymous function. It has a name. The name is "bar", or, more specifically, "foo.bar". What this really is, to my way of thinking, is a function literal. To my way of thinking, a truly anonymous function is a function that really does not have a name, like an argument to another function:

var intervalId = setTimeout(function() { // statements }, 1000);

Now, according to David Flanagan in Javascript: The Definitive Guide, an anonymous function is one that is "created with the Function() constructor." He hedges his bets there, though, because he goes on further to state that such functions are only "sometimes" called anonymous.

Why am I raising this issue here? Because I think if you have a name for something, it can't really be called anonymous. And I think the term "anonymous" with respect to Javascript functions is ambiguous at best, and ought to at least be clarified by someone somewhere.