[wp-hackers] Re: Re: phpDocumentor

[Christian Barmala]

Hi,

thank you for your numerous replies:

"Robert Deaton" <false.hopes at gmail.com> wrote:
> Christian Barmala <christian.barmala at gmx.net> wrote:
>> Is there a reason why WordPress source isn't documented with 
>> phpDocumentor
> A multitude of people volunteered, laid out resources, but Matt pretty 
> much shot it down. The related threads are
> http://comox.textdrive.com/pipermail/wp-hackers/2006-February/004921.html
> http://comox.textdrive.com/pipermail/wp-hackers/2006-March/005481.html

there is even a Codex page on inline documentation: 
http://codex.wordpress.org/Inline_Documentation

>From reading this I go the impression, which Rich describes below.


"Rich Bowen" <rbowen at rcbowen.com> wrote:
> that a feature was requested,  approved by the majority of the community, 
> and even mostly  implemented, but was vetoed by Matt, the lead architect.
> You may choose to read other stuff into that

So let me guess what I'm supposed to read into that: Isn't WordPress 
supposed to be a community project? How can a single person void the whole 
communities opinion? ... or did I get something wrong?


I can't take the "boat"-argument serious. I know multimedia data can 
significantly increase software, but a few lines of documentation shouldn't 
be a space issue in the 21st century.Other arguments sound at least worth 
considering:

http://comox.textdrive.com/pipermail/wp-hackers/2006-February/004948.html :
> it would have to bemore of a make-the-comments-look-pretty-etc function as 
> I am in no position to actually document something.
or http://comox.textdrive.com/pipermail/wp-hackers/2006-February/005083.html 
and 
http://comox.textdrive.com/pipermail/wp-hackers/2006-February/005088.html 
who found the inline doc distracting.



Some of the posts in the above discussion suggested to maintain two versions 
e.g. a commented developer edition and a white space stripped runtime 
edition or Matt's edition and a documented community edition or a separate 
documentation. I don't like this idea, because maintaining two versions is 
an extra overhead and they can easily get out of sync especially if there is 
resistance against one of them.


"Arne Brachhold" <himself at arnebrachhold.de> wrote:
> If you never used this type of documentation you don't know how useful it 
> is. It's not just generating some HTML pages, the main advantage is that 
> some coding editors  use the tags to show the docu when you type the 
> function name or hover about it. With good naming guidelines, you don't 
> even need an extra documentation,

Whether or not code should be documented should not be a matter of 
discussion. Documentation is an integral part of professional development, 
it's 5% extra work to do the documentation according to phpDocumentor (or 
PHPXref or any other inline documentation tool or your choice) rather than 
doing it according to your own preference and the parser readable syntax is 
still human readable. I also agree with Arne that it replaces at least the 
reference manual. You still need a manual in "plain English" which explains 
the concepts and where to start, but this manual doesn't need to be updated 
as frequently as the reference.

Christian