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

[Mike Schinkel]

On Jun 2, 2010, at 12:47 AM, Andrew Nacin wrote:

> On Tue, Jun 1, 2010 at 10:14 PM, Mike Schinkel
> <mikeschinkel at newclarity.net>wrote:
>> 
>> I've been trying to find docs on the $args for register_post_status()
>> somewhere and I can't find anything definitive on Codex or elsewhere.
> 
> It would be best to look at how each is used in core. ... Some of those strings
> are quite unique and you could easily find them with a text search, others
> could be found by searching for "->private" for example -- simply search for
> uses of get_post_status_object().

Sigh. 

I've spent the past five days doing almost nothing but text searches (and tracing through code with a debugger) in WordPress core and plugins as I've been writing a set of plugins that require a deep understanding of core. I've documented with code-wrappers things that have gone undocumented for a long time (like the admin menu system), and things that have just been added (like the nav menu system.) My project which needed to be done Monday night is still only about 60% done because of all the research that it required. 

Then I came across an almost completely undocumented register_post_status() and it occurred to me that the $args were exactly the type of thing that at least someone in the WordPress community knows about and rather than spend another 2-6 hours of doing text searches and tracing code with a debugger I could just ask the list and hopefully learn from the person who knows in a 10th of the time. And I thought the minimum positive side effect that it would end up being documented in the list archives for anyone who needs this kind of thing in the future.  I figured this type of question was appropriate for this list so after being very careful not to post here much lately I decided it would be a reasonable question to ask.  Knowing the nature of the list I expected at least someone to tell me to RTFC but honestly I didn't expect it would be you.  

I guess then I'll just go and spend another 2-6 hours reinventing the wheel.


On Jun 2, 2010, at 9:33 AM, Jeremy Clarke wrote:

> 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. *
> 
> 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.
> 
> 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).

Well said, and +1 on the proposal.

-Mike