Re: [WSG] Usefulness of JSDoc
Hi! Keryx Web: 1. Is JSDoc not a good idea? If so, why not? It's a good idea, but it's not nearly as useful as JavaDoc. I think there are problems arising from the degree to which JavaScript is a dynamic language. 2. If it is, why has it not caught on? Real programmers with experience of automated documentation tools don't care about writing JavaScript. Front-end developers are often not used to set up build script that strips out comments for production code or generate documentation and the like. In a situation today where we use more and more complex JavaScript solutions I think the need for good JavaScript documentation increases. References: http://jsdoc.sourceforge.net/ This project is building a JS documentor in JS on top of the Mozilla Rhino engine: http://code.google.com/p/jsdoc-toolkit/ I have tried both for documenting some of my code, see: http://nornix.sourceforge.net/jsapi/ http://nornix.sourceforge.net/jsapi2/ Both get some things badly wrong. I have tweaked both code and comments to help them out, but the question is if that is a good way to use my time :-) /AndersN *** List Guidelines: http://webstandardsgroup.org/mail/guidelines.cfm Unsubscribe: http://webstandardsgroup.org/join/unsubscribe.cfm Help: [EMAIL PROTECTED] ***
Re: [WSG] Usefulness of JSDoc
I personally wouldn't use it for production websites because it inflates the size of the Javascript file, therefore forcing the user to download more. Also it would tempt others to steal code by making it easy to understand. As a way of documenting code during development and for future reference it would be useful, but well written code should be self-documenting (well named functions) and easy to understand. On 7/25/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? 2. If it is, why has it not caught on? Coming to JS from a back-end developer perspective I find this very strange. Lars Gunther P.S. References: http://jsdoc.sourceforge.net/ http://en.wikipedia.org/wiki/JSDoc *** List Guidelines: http://webstandardsgroup.org/mail/guidelines.cfm Unsubscribe: http://webstandardsgroup.org/join/unsubscribe.cfm Help: [EMAIL PROTECTED] *** -- Ben Wong e: [EMAIL PROTECTED] w: http://blog.onehero.net *** List Guidelines: http://webstandardsgroup.org/mail/guidelines.cfm Unsubscribe: http://webstandardsgroup.org/join/unsubscribe.cfm Help: [EMAIL PROTECTED] ***
[WSG] Usefulness of JSDoc
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? 2. If it is, why has it not caught on? Coming to JS from a back-end developer perspective I find this very strange. Lars Gunther P.S. References: http://jsdoc.sourceforge.net/ http://en.wikipedia.org/wiki/JSDoc *** List Guidelines: http://webstandardsgroup.org/mail/guidelines.cfm Unsubscribe: http://webstandardsgroup.org/join/unsubscribe.cfm Help: [EMAIL PROTECTED] ***
RE: [WSG] Usefulness of JSDoc
-Original Message- [mailto:[EMAIL PROTECTED] On Behalf Of Ben Wong I personally wouldn't use it for production websites because it inflates the size of the Javascript file, therefore forcing the user to download more. Also it would tempt others to steal code by making it easy to understand. As a way of documenting code during development and for future reference it would be useful, but well written code should be self-documenting (well named functions) and easy to understand. So does it make code easy to understand or not? Make your mind up!! Personally, I do try and make use of it, but there are some limitations which I am attempting to work around by writing a script to run at a higher level. Also, code bloat is not a problem, as I run all CSS, HTML and JS through a compaction process as I take it live (automated release system) For most small projects it probably doesn't give much advantage, but I don't really understand how any of the arguments against using JSdoc are different to using JavaDoc. Mike *** List Guidelines: http://webstandardsgroup.org/mail/guidelines.cfm Unsubscribe: http://webstandardsgroup.org/join/unsubscribe.cfm Help: [EMAIL PROTECTED] ***
Re: [WSG] Usefulness of JSDoc
On 7/25/07, [EMAIL PROTECTED] [EMAIL PROTECTED] wrote: So does it make code easy to understand or not? Make your mind up!! Well, that would depend on the quality of the documentation, not on JSDoc. :) Personally, I do try and make use of it, but there are some limitations which I am attempting to work around by writing a script to run at a higher level. Also, code bloat is not a problem, as I run all CSS, HTML and JS through a compaction process as I take it live (automated release system) For most small projects it probably doesn't give much advantage, but I don't really understand how any of the arguments against using JSDoc are different to using JavaDoc. Yep, you're right, the arguments aren't any different. But for those of us who don't have that extra step of compacting the code before deploying, we would have to add it in if we decided to use JSDoc. Whereas, for JavaDoc (and the other doc tools for other languages mentioned) you wouldn't have to worry about it, because the code is not as accessible to the end user as the Javascript because they're run server side or compiled. -- Ben Wong e: [EMAIL PROTECTED] w: http://blog.onehero.net *** List Guidelines: http://webstandardsgroup.org/mail/guidelines.cfm Unsubscribe: http://webstandardsgroup.org/join/unsubscribe.cfm Help: [EMAIL PROTECTED] ***
Re: [WSG] Usefulness of JSDoc
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] ***
