jsdoc-user

Re: [Jsdoc-user] documenting a class?

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

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

Re: [Jsdoc-user] documenting a class?

[Rodrigues, K. <kro...@ne...>]

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

Re: [Jsdoc-user] documenting a class?

[Gabriel R. <gab...@gm...>]

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

Re: [Jsdoc-user] documenting a class?

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

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