[wp-hackers] [PATCH] Documentation

[Rich Bowen]

Andy Skelton wrote:
> On 2/16/06, Rich Bowen <rbowen at rcbowen.com> wrote:
>> +/** current_time( $type = ('mysql'|'timestamp')
>> +*               [ , $gmt = (true|false) ] )
>> +*/
> 
> If this is meant to help people read the code, I think it's too cryptic.

It lists the arguments (type and gmt) with, in this case, their possible
values (type can be either 'mysql' or 'timestamp', and gmt can be either
true or false). The [ ] indicates an optional argument. This syntax is
fairly common in man-page type documentation.

I'm going for API documentation, not "use this to learn how to write
PHP" documentation. It is assumed that folks will be willing to learn
what the notation means. And once you've learned it, the docs become clear.

Please note that this syntax came out of more than an hour of IRC
conversation as being just about the most verbose thing that would
possibly be accepted.

There is a (I think rather unwarranted) fear of making the code files
larger.

However, this isn't a patch that's been accepted. It's proposed. Don't
just say it's too cryptic. Say what you think it should be instead. If
you write a paragraph about what the function does, the patch will
almost certainly be rejected. I've been assured of that by the IRC
conversation. I'd rather not waste time submitting patches that I know
will be rejected.

-- 
Rich Bowen
rbowen at rcbowen.com