Thread: [Jsdoc-user] Fwd: adding code sample/snippet to jsdoc
Status: Inactive
Brought to you by:
mmathews
Menu
▾
▴
jsdoc-user
|
From: Michael M. <mi...@gm...> - 2007-03-02 07:40:15
|
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 =96
>>
>>
>> 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')</=20=
>> 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=92t know =20=
>> how to add yet, like code samples imbedded/commented within the code.
>>
>>
>> Thanks!
>>
>> kate
>>
>> ---------------------------------------------------------------------=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-03-02 21:04:27
|
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
|
|
From: Gabriel R. <gab...@gm...> - 2007-03-02 21:30:24
|
Hi Kate,
Yes, I'd say that that's the path of least resistance then.
Gabriel
On Fri, Mar 02, 2007 at 01:02:25PM -0800, Rodrigues, Kate wrote:
> 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?
>
> 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
> > choose which tags it will process, you very well could invent an
> > @example tag. In that case the example text would be passed into the
> > template as-is.
> >
> > If your template produced HTML, then there is nothing to stop you
> > from having any HTML tags you wanted in the body of your example tag.
> > 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 = nlapiCreateRecord('opportunity')
> > var defaultstatus = record.getFieldValue('entitystatus')
> > </code>
> > */
> > function nlapiCreateRecord(type) { ; }
> >
> > But we are still developing JSDoc-2. When the first beta is released
> > (any day now!) I'll include an example of how to write a template to
> > 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
> > >> a small, illustrative code snippet? Is there anything like an
> > >> @example tag I can put in front of the code snippet to set the
> > >> sample code apart from the function description? Also, bordering
> > >> the code sample do I need to have <code></code> tags so that the
> > >> text will appear in code format?
> > >>
> > >>
> > >> For example:
> > >>
> > >>
> > >> /**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 = nlapiCreateRecord('opportunity')</code>
> > >>
> > >> *<code>var defaultstatus = record.getFieldValue('entitystatus')</
> > >> code>
> > >>
> > >> */
> > >>
> > >> function nlapiCreateRecord(type) { ; }
> > >>
> > >>
> > >>
> > >> Many of the developers around here like the output of JSDoc, but
> > >> they want the output to capture a lot of things I just don't know
> > >> 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
> > >> 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
> > >
> >
> >
> > -------------------------------------------------------------------------
> > 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
>
>
|
|
From: Michael M. <mi...@gm...> - 2007-03-02 22:26:59
|
Wait? Absolutely not! Don't wait. Join the JSDoc-2 group right now and perhaps give us a hand with the work! :-) Seriously though I've been playing with jsdoc-2 for months now and would consider it quite usable already. I'm probably a little biased in that regard but that's why I need folks like yourself to take a look and share their feedback. I look forward to seeing you in the group! http://code.google.com/p/ jsdoc-2/ Regards, Michael On 2 Mar 2007, at 21:02, Rodrigues, Kate wrote: > 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? > > 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 >> choose which tags it will process, you very well could invent an >> @example tag. In that case the example text would be passed into the >> template as-is. >> >> If your template produced HTML, then there is nothing to stop you >> from having any HTML tags you wanted in the body of your example tag. >> 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 = nlapiCreateRecord('opportunity') >> var defaultstatus = record.getFieldValue('entitystatus') >> </code> >> */ >> function nlapiCreateRecord(type) { ; } >> >> But we are still developing JSDoc-2. When the first beta is released >> (any day now!) I'll include an example of how to write a template to >> 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 >>>> a small, illustrative code snippet? Is there anything like an >>>> @example tag I can put in front of the code snippet to set the >>>> sample code apart from the function description? Also, bordering >>>> the code sample do I need to have <code></code> tags so that the >>>> text will appear in code format? >>>> >>>> >>>> For example: >>>> >>>> >>>> /**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 = nlapiCreateRecord('opportunity')</code> >>>> >>>> *<code>var defaultstatus = record.getFieldValue('entitystatus')</ >>>> code> >>>> >>>> */ >>>> >>>> function nlapiCreateRecord(type) { ; } >>>> >>>> >>>> >>>> Many of the developers around here like the output of JSDoc, but >>>> they want the output to capture a lot of things I just don't know >>>> 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 >>>> 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 >>> >> >> >> --------------------------------------------------------------------- >> ---- >> 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 > > > > ---------------------------------------------------------------------- > --- > 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 |
|
From: Gabriel R. <gab...@gm...> - 2007-03-02 20:29:09
|
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
> choose which tags it will process, you very well could invent an
> @example tag. In that case the example text would be passed into the
> template as-is.
>
> If your template produced HTML, then there is nothing to stop you
> from having any HTML tags you wanted in the body of your example tag.
> 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 = nlapiCreateRecord('opportunity')
> var defaultstatus = record.getFieldValue('entitystatus')
> </code>
> */
> function nlapiCreateRecord(type) { ; }
>
> But we are still developing JSDoc-2. When the first beta is released
> (any day now!) I'll include an example of how to write a template to
> 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
> >> a small, illustrative code snippet? Is there anything like an
> >> @example tag I can put in front of the code snippet to set the
> >> sample code apart from the function description? Also, bordering
> >> the code sample do I need to have <code></code> tags so that the
> >> text will appear in code format?
> >>
> >>
> >> For example:
> >>
> >>
> >> /**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 = nlapiCreateRecord('opportunity')</code>
> >>
> >> *<code>var defaultstatus = record.getFieldValue('entitystatus')</
> >> code>
> >>
> >> */
> >>
> >> function nlapiCreateRecord(type) { ; }
> >>
> >>
> >>
> >> Many of the developers around here like the output of JSDoc, but
> >> they want the output to capture a lot of things I just don’t know
> >> 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
> >> 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
> >
>
>
> -------------------------------------------------------------------------
> 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
|
Thanks for helping keep SourceForge clean.
X