[Jsdoc-user] Fwd: documenting a class?

[Michael M. <mi...@gm...>]

Rest easy, I expect the @class tag to remain deprecated in JSDoc-2  
forever -- but it won't be removed. I do hope people appreciate how  
much effort is being made to maintain compatibility with not only  
JSDoc 1.x but also with ScriptDoc. And, of course, JSDoc 1.x is in no  
danger of disappearing. It and the baby will be safe in the bath for  
long into the future.

This does bring up another point, which is, far aside from any tool  
that parses JSDoc comments, what is the "Standard Definition" of  
JSDoc tags? I'd love to have a single definitive list of what tags  
there are and what they mean. I could just write one, but I don't see  
why anyone should care what my opinion is. More important, what are  
the opinions of the users? And what would the process be of  
collecting and distilling those opinions?

If anyone has any thoughts on how to manage such a discussion I'd be  
happy to hear them.

Regards,
Michael

On 3 Apr 2007, at 19:13, bru...@wa... wrote:

>
> Please don't throw out the baby with the bath water with regard to  
> Classes...
> While it is laudable to document the use of JavaScript programmed  
> in the spirit of JavaScript,
> don't forget that many of us ARE simply trying to parallel Java  
> language features (like Classes)
> and that is why we started using JsDoc in the first place!
> Don't take away our illusion that we really are using Java  
> classes. ;-)
> thanks, Bruce
> see..
> http://www.developer.com/lang/jscript/article.php/3657486
> http://www.polyglotinc.com/AJAXscratch/
>
> >The original design for JSDoc wasn't all that clever -- I just copied
> >"how Javadoc does it." Easy for Java programmers to understand but
> >slightly problematic for the rest of us because it abuses the idea of
> >the JavaScript language a bit.
> >
> >As you rightly ask, what is a "class" in JavaScript? JavaScript is a
> >prototype-based language without classes. However, you can think of
> >constructor functions as behaving like classes -- mostly. So
> >essentially any function you intend to invoke with the "new" keyword
> >would be called a "class" by JSDoc.
> >
> >To atone for this sin (it really has been bothering me), I've
> >deprecated the "@class" tag in JSDoc-2 in favor of the "@constructor"
> >tag, which hopefully will better reflect what JavaScript is  
> actually doing.
> ---------------------------------------------------------------------- 
> ---
> Take Surveys. Earn Cash. Influence the Future of IT
> Join SourceForge.net's Techsay panel and you'll get the chance to  
> share your
> opinions on IT & business topics through brief surveys-and earn cash
> http://www.techsay.com/default.php? 
> page=join.php&p=sourceforge&CID=DEVDEV________________________________ 
> _______________
> Jsdoc-user mailing list
> Jsd...@li...
> https://lists.sourceforge.net/lists/listinfo/jsdoc-user