[wp-hackers] Inline Documentation Effort Updates

[Jacob Santos]

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.

Jacob Santos