[wp-hackers] May the discussion on phpdoc never happen again

[Jacob]

Probably would have been nice to have known about 
<http://codex.wordpress.org/Inline_Documentation>, so I could have 
pulled my head out of my ass. 
<http://comox.textdrive.com/pipermail/wp-hackers/2006-February/004921.html> 
and again a few months later. Who knows how many times before 
<http://comox.textdrive.com/pipermail/wp-hackers/2007-October/015584.html>. 
(Props to Ozh and 
<http://comox.textdrive.com/pipermail/wp-hackers/2007-October/015655.html>, 
totally kick ass!).

An aside @deprecated should be (WP Version) and not description as such 
noted. I do not think that it would make since to tell the person that 
the function is deprecated, just when it was. The discussion has already 
passed at that point.

If at the very least, if every function has placeholders, people will 
realize that the discussion has already taken place and then instead of 
having discussions on adding phpdoc comments, the discussion could be 
what the descriptions for functions should be. I wonder if there are any 
objections to this?

/**
 * function_name() - {@internal Missing Short Description}}
 *
 * {@internal Missing Long Description}}
 *
 * @package WordPress
 * @since (WordPress Version)
 */

Add to every WordPress function not already documented. At the very 
least all parameters and return values, along with @since information 
will be added. I've been doing this for most of the functions I don't 
have time for. I find I can spend hours just on 10 to 20 functions and I 
"feel" better if at the very least the parameters and return information 
is added.

http://trac.wordpress.org/ticket/5211 - documents internal WordPress 
functions in wp-settings.php, as well as globals in that file and in 
vars.php and version.php. Any objections to these patches?

I think it is important to also document globals so that plugin and 
hackers don't unintentionally step on others toes and will know what 
globals are available and what purpose they serve and can serve in their 
code.

http://trac.wordpress.org/ticket/5233 - I know this is Matt's baby, but 
I really do think that *every* function means *every* function. The long 
description sucks and it is my only objections. I'm rewriting it to a 
less sucky version... that will still pretty much suck. Not much you can 
write about a function that just pulls in whether not your WordPress 
version is up to date. "Yeah, this function does, oh wait, yeah you 
already know from reading the code. Oops." Anyone not know what 
fsockopen() does? I think I did add an aside that the function would not 
work in some situations. It isn't like any plugins can use the function 
directly.

I'm in the process of completing widgets.php and will create a ticket 
after I've done so. I've yet to look at the rest of the other tickets 
for documentation that exists but current won't commit. However, I'll be 
more incline to submit partial documentation patches that has the above 
phpdoc for most of the files, until which time I find time to go back 
and document the ones that need it. Some functions are so easy that it 
is worth the time to document them right then. However, I think many in 
functions.php can't be said the same about.

It is more or less, I'll feel better about submitting the patches, 
instead of waiting several weeks before I'm able to complete said 
documentation. I think it would be better to have at least some 
documentation than none.

Jacob Santos