[wp-hackers] Re: RE: Re: Re: phpDocumentor

[Christian Barmala]

Brian Layman <brian at thecodecave.com> wrote:
> ... Someone would refactor a section and the old comments would remain and 
> would slowly float away from their orginal
In fact wrong or outdated documentation can be even worse than no 
documentation at all, and since phpDocumentor relies on comments beeing 
properly written by the author, there is a chance that they deviate from the 
actual source. However I see an even bigger risk of deviation with a 
separate documentation on the codex.

> Does PHPDoc somehow mitigate the risk of autocreated comments falling out 
> of date?
phpDocumentor does not autocreate comments. It rather parses manually 
created comments and generates documentation from it. In addition some IDEs 
are phpDocumentor-aware.

BTW: I was thinking of a way to automatically create at least function 
headers with @param definitions. Any ideas?


>  How will it handle code that was checked in by people that did not have 
> PHPDoc active?
You don't need to have phpDocumentor installed. You just have to create or 
update the specially formatted comments.

> Aside from the header (I do like headers btw), how much documentation does 
> the PHPDoc add to the functions' & methods' inner code?
The main elements to document are files, classes, functions/methods 
(parameters and return values) and variables.

>  It almost sounds like every line with a php function gets standard text 
> added to it.
Only function definitions, not the use of a function.

Christian