[wp-hackers] $args for register_post_status()?

[Jeremy Clarke]

On Wed, Jun 2, 2010 at 12:47 AM, Andrew Nacin <wp at andrewnacin.com> wrote:

>
> I imagine the post status API will improve in a future release. It's new in
> 3.0 and thus we'll wait to see how it is used, how it could be used, and
> what we want to do with it, not unlike how register_post_type came to be
> first in 2.9, and how it took some time for full UI exposure in custom
> taxonomies.
>
>
While this is a logical perspective on the API as a whole (and specifically
how it is exposed in the automatic UI), I don't think it makes up for the
obvious lack of documentation in register_post_type(). In the PHPDoc there
is a specific section defining optional $args contents but it only has three
of the 16 possibilities defined. Why are those three present and not the
others? Is there a reason other than updates to the function that were
either rushed or lazy?

IMHO this is an example of a commit that fails to document the changes it
entails, which happens pretty often in WP, leaving new functionality obtuse
and hard to test for people who would otherwise be finding its bugs and
defining its points that need work.

*Proposal: Any time an argument is added to a function the changeset should
not be committed until relevant PHPDoc sections have been updated to reflect
the change. *

Is that controversial? Isn't it in line with where WP has been coming for
years and where it wants to go?

Always keeping phpdoc updated when making changes also has the wonderful
side effect that when you look at the diff on trac you see both the new code
and the new description. It makes things easier in so many different ways.

IMHO, the process of updating PHPDoc also has an editorial effect on code
and API writing. When you have to spell out in sentences what each function
is supposed to do you tend to realize the dumb parts at that point, rather
than after they are committed.

I'm pretty sure most people already agree with this system. I know that I
always document my own patches simply because it increases their likelihood
of being understood and committed. It would be good to see more consistency
with this from the core committers though, even when they are working on
code that is still in flux. Documenting prototype code will help others
understand what you are doing and test it properly, rather than hacking
around guessing at what you might have done, and when the final product is
ready it will be fully documented (and even the documentation will have been
read by the testers, so it itself will have had chances for revision during
the initial testing process).

-- 
Jeremy Clarke | http://jeremyclarke.org
Code and Design | http://globalvoicesonline.org