I like the following layout..
Name Object etc
Syntax
object.method and so on...
Collections and etc.
Methods
Events
Remarks
Howto... and issues
Example
code...
Just my tip of the coin :)
/Daniel
> 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.../
|
