Thread: Re: [Jsdoc-user] documenting a class?
Status: Inactive
Brought to you by:
mmathews
From: Michael M. <mi...@gm...> - 2007-04-03 06:18:38
|
Hi Kate, The original design for JSDoc wasn't all that clever -- I just copied =20= "how Javadoc does it." Easy for Java programmers to understand but =20 slightly problematic for the rest of us because it abuses the idea of =20= the JavaScript language a bit. As you rightly ask, what is a "class" in JavaScript? JavaScript is a =20 prototype-based language without classes. However, you can think of =20 constructor functions as behaving like classes -- mostly. So =20 essentially any function you intend to invoke with the "new" keyword =20 would be called a "class" by JSDoc. To atone for this sin (it really has been bothering me), I've =20 deprecated the "@class" tag in JSDoc-2 in favor of the "@constructor" =20= tag, which hopefully will better reflect what JavaScript is actually =20 doing. Regards, Michael On 3 Apr 2007, at 02:19, Rodrigues, Kate wrote: > All =96 > > > I was asked by someone in my group if, using JSDoc, I am going to =20 > provide high level descriptions at the top of each =93class=94 page =20= > (similar to the figure below). As I=92ve stated to the group, I am =20 > new to documenting JavaScript, so I=92m not quite sure what =20 > constitutes a =93class=94 in JavaScript. If I=92m documentation for =20= > JavaScript functions, objects, and methods, which is considered the =20= > class? Based on your response, which @ tag do I use within my =20 > JavaScript file to document a class? > > > Thanks a million! > > kate > > > > <image001.jpg> > > <image001.jpg> > ----------------------------------------------------------------------=20= > --- > Take Surveys. Earn Cash. Influence the Future of IT > Join SourceForge.net's Techsay panel and you'll get the chance to =20 > share your > opinions on IT & business topics through brief surveys-and earn cash > http://www.techsay.com/default.php?=20 > page=3Djoin.php&p=3Dsourceforge&CID=3DDEVDEV____________________________= ____=20 > _______________ > Jsdoc-user mailing list > Jsd...@li... > https://lists.sourceforge.net/lists/listinfo/jsdoc-user |
From: Rodrigues, K. <kro...@ne...> - 2007-04-03 17:07:34
|
Michael and Gabriel - Thank you both for your responses! Your information totally answered my question. Also, thanks for helping me out the other week by showing me how to create a custom @example tag. I'd still like to figure out a way to ensure that the contents of this tag always appear AFTER all the other tags. One of your emails said there is no way to enforce this and that the only downside of a custom tag is that there's no telling where the information will appear (in other words, the "example" text could appear after the @returns info, it could appear before @returns, it could appear after @throws - - there is no way to specify where the example will appear). Is this true with all custom tags, or was this just true for the sample code snippet that you provided to me: =20 $METHOD_ATTRS_MAP{example} =3D sub { my $ex =3D $_[0][0]; return "<div style=3D'background: #CCCCCC; border: dashed = 2px; padding: 12px; width: 70%'> <code>$ex</code></div>"; };=20 =20 thanks so much, kate =20 -----Original Message----- From: Michael Mathews [mailto:mi...@gm...]=20 Sent: Monday, April 02, 2007 11:19 PM To: jsd...@li... Cc: Rodrigues, Kate Subject: Re: [Jsdoc-user] documenting a class? =20 Hi Kate, =20 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. =20 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. =20 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. =20 Regards, Michael =20 =20 On 3 Apr 2007, at 02:19, Rodrigues, Kate wrote: All - =20 I was asked by someone in my group if, using JSDoc, I am going to provide high level descriptions at the top of each "class" page (similar to the figure below). As I've stated to the group, I am new to documenting JavaScript, so I'm not quite sure what constitutes a "class" in JavaScript. If I'm documentation for JavaScript functions, objects, and methods, which is considered the class? Based on your response, which @ tag do I use within my JavaScript file to document a class?=20 =20 Thanks a million! kate =20 =20 <image001.jpg> <image001.jpg> ------------------------------------------------------------------------ - 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=3Djoin.php&p=3Dsourceforge&CID=3D= DEVDE V_______________________________________________ Jsdoc-user mailing list Jsd...@li... https://lists.sourceforge.net/lists/listinfo/jsdoc-user =20 |
From: Gabriel R. <gab...@gm...> - 2007-04-03 18:25:11
|
Hi Kate, > Thank you both for your responses! Your information totally answered my > question. Also, thanks for helping me out the other week by showing me > how to create a custom @example tag. I'd still like to figure out a way > to ensure that the contents of this tag always appear AFTER all the > other tags. One of your emails said there is no way to enforce this and > that the only downside of a custom tag is that there's no telling where > the information will appear (in other words, the "example" text could > appear after the @returns info, it could appear before @returns, it > could appear after @throws - - there is no way to specify where the > example will appear). Is this true with all custom tags, or was this > just true for the sample code snippet that you provided to me: > Your understanding of custom tags in JSDoc is correct: there currently isn't a way of forcing the order in which they're rendered in the documentation. If you feel that this is something you'd like to use, I could certainly look into improving this functionality in JSDoc. I've basically left the original functionality as it is since I first wrote it, as there hasn't ever been all that much interest in the custom tag construct as it currently stands. Regards, Gabriel |
From: Michael M. <mi...@gm...> - 2007-04-03 19:33:38
|
I'm on the verge of begging you to try JSDoc-2 now. The order of tags, custom or otherwise, is completely under your control. I understand if you don't have time to try a tool that is still in beta, but your feedback could in fact help us get to the final 1.0 release that little bit faster. In any case JSDoc-2 will eventually be finalized (I expect in June/July), and I hope you'll find it will solve these issues. Regards, Michael On 3 Apr 2007, at 19:25, Gabriel Reid wrote: > Hi Kate, > >> Thank you both for your responses! Your information totally >> answered my >> question. Also, thanks for helping me out the other week by >> showing me >> how to create a custom @example tag. I'd still like to figure out >> a way >> to ensure that the contents of this tag always appear AFTER all the >> other tags. One of your emails said there is no way to enforce >> this and >> that the only downside of a custom tag is that there's no telling >> where >> the information will appear (in other words, the "example" text could >> appear after the @returns info, it could appear before @returns, it >> could appear after @throws - - there is no way to specify where the >> example will appear). Is this true with all custom tags, or was this >> just true for the sample code snippet that you provided to me: >> > > Your understanding of custom tags in JSDoc is correct: there currently > isn't a way of forcing the order in which they're rendered in the > documentation. > > If you feel that this is something you'd like to use, I could > certainly > look into improving this functionality in JSDoc. I've basically > left the > original functionality as it is since I first wrote it, as there > hasn't > ever been all that much interest in the custom tag construct as it > currently stands. > > Regards, > > Gabriel > > ---------------------------------------------------------------------- > --- > 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 |