Re: [Jsdoc-user] Fwd: adding code sample/snippet to jsdoc

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

My knowledge of perl is next to nothing. Should I wait for JSDoc-2 to be =
released rather than try to figure out how to add a custom @example tag =
to the current JSDoc-1 config file?
=20
thanks!
kate

________________________________

From: Gabriel Reid [mailto:gab...@gm...]
Sent: Fri 3/2/2007 12:28 PM
To: jsd...@li...
Cc: Rodrigues, Kate
Subject: Re: [Jsdoc-user] Fwd: adding code sample/snippet to jsdoc



Hi,

As Michael pointed out, JSDoc-2 has much stronger support for custom
constructs such as this one. However, JSDoc 1 also has very basic
support for this as well, in the not-very-well-known .jsdoc_config file.
Adding support for new tags *does* require that you have at least a =
basic
understanding of perl, as this configuration file consists of perl
callbacks for custom tags.

On the other hand, of course, you could simply put the example code
inside of <code> tags, which might just be sufficient.

Regards,

    Gabriel


On Fri, Mar 02, 2007 at 07:40:07AM +0000, Michael Mathews wrote:
> Hi,
>
> Gabriel can answer for JSDoc 1.x but because JSDoc-2 doesn't pick and=20
> choose which tags it will process, you very well could invent an=20
> @example tag. In that case the example text would be passed into the=20
> template as-is.
>
> If your template produced HTML, then there is nothing to stop you=20
> from having any HTML tags you wanted in the body of your example tag.=20
> In JSDoc-2 your tag could look like this:
>
> /**
> nlapiCreateRecord - Initializes a new record and returns an
> nlobjRecord containing all the default field data for that record type
> @param type - record type for the record
> @example The following example initializes a new opportunity record.
> <code>
> var record =3D nlapiCreateRecord('opportunity')
> var defaultstatus =3D record.getFieldValue('entitystatus')
> </code>
> */
> function nlapiCreateRecord(type) { ; }
>
> But we are still developing JSDoc-2. When the first beta is released=20
> (any day now!) I'll include an example of how to write a template to=20
> handle example tags.
>
> Regards,
> Michael
> >
> > On 1 Mar 2007, at 23:07, Rodrigues, Kate wrote:
> >
> >> Hi there -
> >>
> >>
> >> In my JavaScript file, is there a javadoc tag I can use to set off=20
> >> a small, illustrative code snippet? Is there anything like an=20
> >> @example tag I can put in front of the code snippet to set the=20
> >> sample code apart from the function description? Also, bordering=20
> >> the code sample do I need to have <code></code> tags so that the=20
> >> text will appear in code format?
> >>
> >>
> >> For example:
> >>
> >>
> >> /**Initializes a new record and returns an nlobjRecord containing=20
> >> all the default field data for that record type
> >>
> >> *@param type  record type for the record
> >>
> >> *@example the following example initializes a new opportunity =
record
> >>
> >> *<code>var record =3D nlapiCreateRecord('opportunity')</code>
> >>
> >> *<code>var defaultstatus =3D record.getFieldValue('entitystatus')</
> >> code>
> >>
> >> */
> >>
> >> function nlapiCreateRecord(type) { ; }
> >>
> >>
> >>
> >> Many of the developers around here like the output of JSDoc, but=20
> >> they want the output to capture a lot of things I just don't know=20
> >> how to add yet, like code samples imbedded/commented within the =
code.
> >>
> >>
> >> Thanks!
> >>
> >> kate
> >>
> >> =
---------------------------------------------------------------------
> >> ----
> >> 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?
> >> =
page=3Djoin.php&p=3Dsourceforge&CID=3DDEVDEV_____________________________=
__
> >> ________________
> >> Jsdoc-user mailing list
> >> Jsd...@li...
> >> https://lists.sourceforge.net/lists/listinfo/jsdoc-user
> >
>
>
> =
-------------------------------------------------------------------------=

> 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=
DEVDEV
> _______________________________________________
> Jsdoc-user mailing list
> Jsd...@li...
> https://lists.sourceforge.net/lists/listinfo/jsdoc-user