Re: [Phpgroupware-developers] Code documentation

[Chris Weiss]

php.net's whole website is in a cvs server, and you can view any pages source 
via a
link at the bottom.  it almost looks like the online manual is generated with te
comments added at teh bottom on each page.  Looking at their doc team how-to 
they
use DocBook for everything then have export scripts run in daily batches.





Dan Kuykendall (address@hidden) wrote:
>
>Chris Weiss wrote:
>
>> this brings up an old topic warmed over...
>> are we going to move from our inline docs to phpdoc?
>> will phpdoc do what our inline does now? it did't used to but that was some 
>> time ago.
>> will phpdoc help make a online user commentable site like php's online 
>> manual?
>> is there another doc package that would suit our needs better now?
>
>This is something that really has never been fully decided.
>
>phpdoc is just like javadoc, so it uses inline comments, which isnt all
>that good for us.
>
>I wrote the inline doc parser we were going to use. I could easily
>finish it in another day, but once building it I noticed MANY problems
>with using such a method.
>
>1) Having multi versions of the same class, such as with our db classes,
>causes duplication in documentation effort and a bunch of unneeded
>resulting documentation. We should only document the db class once, and
>users will know it will always work the same no matter which database
>they are using.
>
>2) Having the comments in the php files DOES slow down the run time end
>of things. The problem is that the files are larger and as a result
>consume more memory when loaded.
>
>3) This means that API documentation can only be maintained by the API
>developers, who are not all that good about maintaining the docs :-p
>
>
>We need a solution that can work like the php.net website does, in that
>we can maintain the documentation and also allow users to add comments.
>I dont know what solution the PHP guys use, but we need to rip the
>documentation out of the .php files and into something more easily
>maintained by a more flexible group.
>
>Dan
>
>
>
>_______________________________________________
>Phpgroupware-developers mailing list
>address@hidden
>http://mail.gnu.org/mailman/listinfo/phpgroupware-developers
>