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

[Dan W. <da...@wi...>]

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
http://dan.willemsen.us/


Quoting sp...@4m...:

> Documentation Stratagy for DynApi; is there one??
> =================================
> 
> How do *you* plan to document DynApi code? 
> 
> I had the problem that I needed inline documentation for my javascripts
> (like javadoc for java and phpDocumentor for PHP).
> 
> E.g.
> /**
> * Follwing is a short description.
> * A longer description goes here.
> * 
> * @access public 
> * @param int i Starting point in pixel
> * @param string s Caption
> * @return object A new dynapi object
> * @see setEnd()
> */
> setStart(i, s) = function {
>   // the code
> }
> 
> 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.
> 
> 
> 
> -------------------------------------------------------
> This SF.Net email is sponsored by: INetU
> Attention Web Developers & Consultants: Become An INetU Hosting Partner.
> Refer Dedicated Servers. We Manage Them. You Get 10% Monthly Commission!
> INetU Dedicated Managed Hosting http://www.inetu.net/partner/index.php
> _______________________________________________
> Dynapi-Dev mailing list
> Dyn...@li...
> http://www.mail-archive.com/dyn...@li.../
>