[Phpgroupware-developers] Code documentation

[Dan Kuykendall]

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