Commenting JavaScript functions á la Python Docstrings

Question

It is valid JavaScript to write something like this:

function example(x) {
    "Here is a short doc what I do.";
    // code of the function
}

The string actually does nothing. Is there any reason, why one shouldn't comment his/her functions in JavaScript in this way?

Two points I could think of during wiriting the question:

• The string literal must be initiated, which could be costly in the long run

• The string literal will not be recognized as removable by JS minifiers

Any other points?

Edit: Why I brought up this topic: I found something like this on John Resig's Blog, where the new ECMA 5 standard uses a not assigned string literal to enable "strict mode". Now it was my interest to just evaluate, if there could be uses or dangers in doing such documentation.

Answer 1

There's really no point in doing this in Javascript. In Python, the string is made available as the __doc__ member of the function, class, or module. So these docstrings are available for introspection, etc.

If you create strings like this in Javascript, you get no benefit over using a comment, plus you get some disadvantages, like the string always being present.

Answer 2

I was looking for a way to add multi-line strings to my code without littering it with \n's. It looks like this module fits the bill: https://github.com/monolithed/doc

Unfortunately, the comments won't survive minification, but I suppose you could write a compile task to convert docstrings to "\n" format.