Re[2]: [Dynapi-Dev] Documentation Stratagy for DynApi; is there one? ?

[<bs...@in...>]

 [Dynapi-Dev] Documentation Stratagy for DynApi; is there one??

Following comment to the suggestion of using 
'jsdoc' as documentation tool:

'jsdoc' is an half dad 2year old project!
An eary beta staged SW with only a minimum on 
functionallity and hardly any doc.

And look at the statistics of 'jsdoc':
http://sourceforge.net/project/stats/?group_id=30801
300 lausy downloads, 0 bug corrections in 2 years and 
falling intrest of the community.

Put this in relation to a living project like the phpDocumentor 
http://sourceforge.net/project/stats/?group_id=11194
with 19'548 downloads and 554 bug correction over 
the last 3 years and ask your self what you want to bet 
your money on.

DON'T REALY ON 'jsdoc'! 

I still hope to get more feedback on my offer to help 
out with a php solution. NOTE: PHP can now be used 
as standalone script interpreter (just like perl). 


> this is the type of thing I have been planning to do to generate 
> the quickref documentation, but haven't been able to yet.  
> I just found phpDocumentor yesterday, and was thinking 
> about writing another parser for it, javascript, but
> that looks like to much work for me.
> --
> Dan Willemsen

My suggestion is not about changing the code of 
phpDocumentor. Just want to make that clear.
I change the js-code to look like PHP code and then 
use the phpDocumentor to parse the doc from it 
(See below)

--
Regards Sam 

=========================================
> 
> --- Darin Kadrioski <DKa...@lm...>
> wrote:
> > http://sourceforge.net/projects/jsdoc/
> 
> Well this is something to look into for those working
> on the Docs for DynAPI.
> 
> --
> Raymond Irving
> 
>
> -----Original Message-----
> From: dyn...@li...
> [mailto:dyn...@li...]On
> Behalf Of
> sp...@4m...
> Sent: Thursday, June 26, 2003 4:36 PM
> To: dyn...@li...
> Subject: [Dynapi-Dev] Documentation Stratagy for
> DynApi; is there one??
>
> Documentation Stratagy for DynApi; is there one??
> =================================
> 
> How do *you* plan to document DynApi code? 
> 
*snip*
> But I'm not aware that anthing exsists for js. So
> wath I did is: I wrote a simple converter that converts 
> js to PHP. Not 100% but good enough for
> the phpDocumentor to think it's valid PHP and let
> the converter do the HTML/PDF documenting 
> rendering work (including links aso).
> 
> The 'drawback' (if you can say so) is that I needed
> to write js code in a form that makes it easy to detect 
> classes and methods. My suggestion is following 
> code style:
> 
> /**
> * This is a sample class.
> * 
> * @example example_1.html
> *
> * @author    xxx
> * @package   core
> * @subpackage fx
> * @copyright LGNU
> */
> aClass = function() {
>   
>   /**
>   * Follwing is a short description.
>   * A longer description goes here.
>   * 
>   * @access public 
>   * @param object e Any object
>   * @return void
>   * @see onpathrun(), onpathstop()
>   */
>   this.onpathstart = function(e) {
>     status = start;
>   }
>   
>   // a.s.o.
> 
> }
> 
> I forgot to mention that the js files must go
> through a stripper. The  stripper removes all 
> comments and (if intelligent) can squeeze the
> js to a max. The striped js code is for productive
> use. While the original files stay commented!
> 
> In this way the doc and the source stay in sync.
> Separating code form doc is a very very dangerous 
> and will cause head acks for everybody! 
> 
> If you are thinking of maintaining doc separate from
> source, please, *please* over think you strategy. 
> I on my side am willing to share my
> knowledge on how to strip the js-code and give you a
> hand on the converter and phpDocumentor.