Re: [Phpgroupware-developers] Re: Standard source code header and php Documentor

[Dan Kuykendall]

Ralf Becker wrote:

> My thoughts about docs:
>
> 1) I vote for inline-docs for documenting the functions and arguments. 
> In my opinion everything else will never be very up-to-date.

Its not completely up to date even as inline-docs. I used to share your 
opinion on this, but it has really proven to not work as expected.


> I completly 
> disagree with probiz that nothing is documented in the API. I personly 
> document everything, which is not, when I touch that class or function. 

Yes, there is a good deal of documentation done, but inline-docs still 
have the problem of lots of duplicate data because of the number of each 
class (db, accounts, auth, etc...)

> Still the points of the discussion are very small, as the differences in 
> our existing inline-doc-standard and the php-doc standard. With a view 
> lines of customisation (far less lines as the disscussion alread took 
> ;-) ) the existing parsers could be modified to read both.

Updating the current docs to whatever new format is desired would not be 
hard. I prefer to dump out the comments to docbook, and then yank them 
from being inline as mentioned.


Here are the reasons I have for moving away from inline-docs, to a 
seperate external solution.

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


Dan