On 25/07/07, Keryx Web <[EMAIL PROTECTED]> wrote:
Hi all!
I have been wondering about the (absent) standard for documenting
JavaScript: JSDoc.
In PHP one can expect any seasoned developer to use PHPDocumentor (or
something similar, like Doxygen). In JAVA one would expect Javadoc to be
used by most.
However, except for Foundations of Ajax (ISBN 1-59059-582-3) I see *no*
other book on the market using or promoting the use of JSDoc. And as far
as I know YUI is the only major library to use it.
"Gurus" like David Flanagan, John Resig, Christian Heilmann, Dean
Edwards and PPK are all silent on this matter, and do not use JSDoc in
any code I've seen them write. Admittedly they write a lot, but JSDoc
are absent from their books and blogposts, at least.
1. Is JSDoc not a good idea? If so, why not?
It's a pretty good idea, but with many of the same arguments against
it as for JavaDoc. But if you ask me, it's not the right tool. A tool
based on JavaDoc will miss some fundamentals of ECMAScript, especially
with ES4 coming soon.
Some examples:
- In a world where both class-based inheritance and prototype-based
delegation exist, both must be distinct. A constructor function, an
interface and a class do not represent the same relations, and do not
work in the same way. This is true also for ECMAScript 3 which doesn't
have class-based inheritance, because implementations have
environments that use class-based inheritance. (E.g. in Mozilla the
implementation of the HTMLElement interface is placed on the direct
implementor class. Overriding properties on HTMLElement.prototype will
not work when the actual implementation lies on HTMLSpanElement class)
- It doesn't make distinctions where distinctions should be made. A
parameter is not the same as an argument.
- It fails to take the closure concept into consideration, together
with the privacy facility it provides.
- It fails to take the fact there are three different kinds of object
typing that can be used into account:
* There are primitive types/value types (number, boolean) and
compound types/reference types (objects, functions) and a primitive
type with copy-on-write semantics (string).
* There are classes (String, Object, Number, Array, one each for
most DOM interfaces etc. )
* There are constructor function/prototype chains (Which are NOT
the same as the above classes)
2. If it is, why has it not caught on?
For several reasons. One, I believe, is that autogenerating
documentation has not caught on in the client side web dev world.
There are very few large libraries for ECMAScript compared to other
scripting languages, probably because of the entirely different
environments the code lives in: The code is actually sent over the
wire in raw form. You want to minimise the weight of the sent code, so
you don't want to send documentation in the form of comment systems.
(You can use a compilation step here to remove dead weight but keep
the original in fully commented form, of course - compiling to
minimised ECMAScript). A compiled language doesn't have this
restriction, so for example Flash or Java will have entirely different
models for commenting. And server side languages don't send code at
all, they just send results. The code size server side has entirely
different impact because of that.
Coming to JS from a back-end developer perspective I find this very strange.
The perspective difference is quite a lot of the reason, I feel.
Different considerations give different behaviour.
--
David "liorean" Andersson
*******************************************************************
List Guidelines: http://webstandardsgroup.org/mail/guidelines.cfm
Unsubscribe: http://webstandardsgroup.org/join/unsubscribe.cfm
Help: [EMAIL PROTECTED]
*******************************************************************
