[wp-hackers] Re: RE: Re: Re: phpDocumentor
christian.barmala at gmx.net
Thu Jul 6 15:15:20 GMT 2006
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
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.
More information about the wp-hackers