dynapi-dev

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

[Darin K. <DKa...@lm...>]

http://sourceforge.net/projects/jsdoc/

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

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

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

[Raymond I. <xw...@ya...>]

--- 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? 
> 
> 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.../
> 
> 
>
-------------------------------------------------------
> 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.../


__________________________________
Do you Yahoo!?
SBC Yahoo! DSL - Now only $29.95 per month!
http://sbc.yahoo.com

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.

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

[<sp...@4m...>]

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

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

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

Quoting Darin Kadrioski <DKa...@lm...>:

> http://sourceforge.net/projects/jsdoc/

nice... the only question i have is whether it will parse some of the javascript
that we use in dynapi, some of it isn't all so well-formed according to it's
definition i don't think

--
Dan Willemsen

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

[Raymond I. <xw...@ya...>]

--- Dan Willemsen <da...@wi...> wrote:
> 
> Quoting Darin Kadrioski
> <DKa...@lm...>:
> 
> > http://sourceforge.net/projects/jsdoc/
> 
> nice... the only question i have is whether it will
> parse some of the javascript
> that we use in dynapi, some of it isn't all so
> well-formed according to it's
> definition i don't think

"...With the exception of the rules stated above how
you document your code is not a matter of concern to
the parser...."

As long and the comments follow the jsDoc rules then
the DynAPI files will work great!

I think this a good start for the source codre
documentation.

The question now is who are the persons that will be
working on the source code documentation?  Dan I guess
your in on this one?


--
Raymond.

> --
> Dan Willemsen
> 
> 
> 
>
-------------------------------------------------------
> This SF.Net email sponsored by: Free pre-built
> ASP.NET sites including
> Data Reports, E-commerce, Portals, and Forums are
> available now.
> Download today and enter to win an XBOX or Visual
> Studio .NET.
>
http://aspnet.click-url.com/go/psa00100006ave/direct;at.asp_061203_01/01
> _______________________________________________
> Dynapi-Dev mailing list
> Dyn...@li...
>
http://www.mail-archive.com/dyn...@li.../


__________________________________
Do you Yahoo!?
SBC Yahoo! DSL - Now only $29.95 per month!
http://sbc.yahoo.com