[wp-hackers] Inline Documentation Effort Updates
wordpress at santosj.name
Fri Sep 26 04:35:56 GMT 2008
Ryan McCue wrote:
> Peter Westwood wrote:
>> The root of the site is http://phpdoc.ftwr.co.uk/ and it is set to
>> automattically update every 30 minutes as things change.
> *wonders if the mispelling of "automatically" was on purpose* :-P
> Also, Jacob, thanks for all your work on this. It's really great to be
> able to have developer documentation for the code and it's made creating
> plugins, patches and, really, everything much easier. My only regret is
> that I wasn't able to help and I apologise for that.
Oh yeah, Ryan Boren has added http://phpdoc.wordpress.org/trunk/ and
http://phpdoc.wordpress.org/tags/2.6.2/ and I suspect that when 2.7
comes out, that will also be added. Peter Westwood also bought his sites
back up for more than just WordPress, which is pretty cool.
I don't want anyone to feel back for not helping. I actually learned a
lot and had some fun doing it (well, I wouldn't have put as much effort
in it if it wasn't at least a little bit fun). I think it is fine that
the community are writing patches that includes inline documentation and
I think it is great that the core commit team developers are adding
inline documentation for new functions. It is absolutely fantastic, that
the majority of the core team is writing inline documentation. That was
mostly the whole point of the effort in the first place. The theory was
that no one felt like adding inline documentation, because inline
documentation didn't exist and if it did exist, then more people will
write inline documentation. It appears the theory was correct. I like to
feel that I had something to do with it, but I'm sure with the ratio of
code to comments, that the core team was already doing so before I started.
The contention I have, has always been quality assurance, which when I
joined the community WordPress had very little. Or at least very little
that could be seen. That has changed, not because of me, but because of
the community and Automattic. I applaud that as a PHP developer, I don't
have to feel dirty for using WordPress, when there are supposed "better"
developed alternatives out there. You know, with inline documentation
and unit tests. WordPress has both of those and as an user of WordPress,
I'm very happy of the gains WordPress has made because of the community.
All open source projects have problems with motivating community members
to take action. PHP, the language has the same problem. Well, they have
more people working on the developer manual of the language than
actually writing inline documentation, but I mean they could use more
people writing test cases for extensions. There is a long list of people
on the http://codex.wordpress.org/Inline_Documentation to thank that
helped out a great deal. Most of them in the past and several in the
present. I predict more to come in the future.
As a developer, I also enjoy that I can look at the WordPress source or
phpDocumentor sites and get API documentation for WordPress functions. I
might have documented a lot of functions, but I'll be damned if I can
remember them all. Using PDT, has also gained some enjoyment, since it
displays the short description and parameter information (sadly the long
description is not shown). I just kind of wished that it existed when I
started writing plugins, but at least those that start writing plugins
for WordPress 2.7 won't have as hard of a time finding functions.
If anyone wishes to help there is a ticket devoted to the mistakes in
the documentation for each milestone, named "Inline documentation
corrections..." or search for the keyword "phpdoc" find that ticket and
submit the patch. Doesn't matter if it only changes one word or changes
the entire function level phpdoc block.
We as a community need to help out with the quality assurance of
WordPress, well some of us do. I think what you do, Ryan, is great, so
keep doing it. No apology is needed. I'm actually more mad at the early
developers for not writing the inline documentation themselves. What it
would have saved if the effort gained support in 0.70, 1.0, but it
solves nothing blaming those who are gone.
The next step I think is improving the level of testing automation,
which is boring, fun, and a larger task to complete than inline
documentation. Thankfully, there are already several people working on
it already (http://svn.automattic.com/wordpress-tests), so helping with
that will also go a long way.
Actually, post-template.php is halfway complete, so I'm pretty sure I'll
be finishing that one up before the end of this weekend. I'm still not
sure about link-template.php, but it would be a shame to have one file
just hanging out there all alone. I'm thinking I might finish it up, but
I won't be mad, if someone completes it before I do.
More information about the wp-hackers