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

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

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
> 
>