[wp-hackers] Re: Re: phpDocumentor
christian.barmala at gmx.net
Thu Jul 6 09:49:47 GMT 2006
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
> A multitude of people volunteered, laid out resources, but Matt pretty
> much shot it down. The related threads are
there is even a Codex page on 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
> it would have to bemore of a make-the-comments-look-pretty-etc function as
> I am in no position to actually document something.
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.
More information about the wp-hackers