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

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

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