[wp-hackers] Inline Documentation Effort Updates

[Jacob Santos]

The conclusion of the April discussion on how I hate that no one has 
stepped forward to help out on the Inline documentation effort was that 
I would continue and wait to see if anything else happened. This is an 
update of the inline documentation effort and what has happened in the 
four months, since that last thread.

To rehash what the inline documentation effort is, it is to push 
community members into helping out writing inline documentation for 
WordPress in order to complete it quickly or faster than one person can 
accomplish at least. The point also is to ensure that future functions 
are included with inline documentation negating the need for another 
grassroots effort in the future.

Well, happy to say that all but two files in wp-includes directory have 
incomplete documentation. Two people have stepped forward to help with 
the effort in completing both formatting.php (which is a pain, so I'm 
happy I didn't have to work on it) and general-template.php. Scott H and 
Peter Westwood worked on those two files respectively. Not the masses I 
had hoped for, but those two were able to complete a large portion of 
the files, so I think it is all good.

Most of the new functions that are added also have inline documentation. 
Not all, mind you, but enough that I think the effort was successful in 
convincing enough people to put the effort into adding inline 
documentation. Also, the functions that were added without inline 
documentation didn't take more than an hour to complete the inline 
documentation, so I don't think I'm upset about that.

The entire WordPress base directory has complete inline documentation. 
Most of the files in wp-admin has file block level inline documentation 
and all should have file block level inline documentation by the time 
WordPress 2.7 is released. This will mean that any PHPXRef site out 
there will actually have descriptions for files on the right hand side. 
It also means that a lot of the wp-admin functions are documented. Not 
the wp-admin/includes functions.

The only parts that are missing are a few files in wp-admin are missing 
function level inline documentation, Most of wp-admin/includes files are 
missing inline documentation. The functions that can be used by plugin 
or theme developers have priority, but that progress is only halfway 
complete. That directory just isn't that high on the priority list, but 
if anyone wants to document those files, they may well do so.

Alas, the final pieces for the inline documentation effort is in 
link-template.php and post-template.php (which I'm still might complete 
before the week is over). So for WordPress 2.7, you will be able to look 
up most functions and have inline documentation for the parameters and 
descriptions for what the functions do.

Just so you know, the inline documentation effort is never complete. 
There are grammar mistakes, documentation inaccuracies, and well the 
inline documentation could always be improved and expanded.

So it has been a year, but I think the inline documentation has been a 
success (October 2007 - September 2007). I hope that if anyone spots a 
mistake, that they correct it and submit the patch to the WordPress 
Trac. I'm pretty much done with the effort, so if anyone wants to 
continue, please don't ask, just go ahead and do it. If not, then I'll 
probably take it up again sometime next year.

Jacob Santos