[wp-hackers] Inline Documentation Effort Updates

[Viper007Bond]

Great work, Jacob. Your work, as well as Scott H and Peter Westwood's, is
much appreciated.

On Wed, Sep 24, 2008 at 6:27 PM, Jacob Santos <wordpress at santosj.name>wrote:

> 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
> _______________________________________________
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-hackers
>



-- 
Viper007Bond | http://www.viper007bond.com/ | http://www.finalgear.com/