[wp-hackers] Inline Documentation Effort Updates
wordpress at santosj.name
Thu Sep 25 01:27:43 GMT 2008
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.
More information about the wp-hackers