[wp-hackers] Would providing PHPdoc templates for all included files be committed?

[Jacob]

One of the major pushes I would like propose is at least getting a 
phpdoc structure for every PHP function in wp-includes/. This would 
leave out the short description and long description for the functions 
that weren't finished. If the patches and proposal are rejected as is, 
then I'll still continue to document and finish as many files as 
possible. The end result in the worse case is less files would be 
documented or appear to be documented and the templates for each file 
will remain patches under their respective tickets until someone comes 
along and finishes the patch. Either way shouldn't be as bad.

*Well, there are several problems that I feel need to be addressed with 
this proposal.*

1. It will appear quite ugly to have every undocumented function with 
{@internal Missing Short Description}} and {@internal Missing Long 
Description}}.

While I agree, it would allow for those people to just replace those 
areas with their text and submit a patch. It would remove the need for 
them to also document parameters and return types. It would also make 
clear that the devs are aware that documentation is missing in those 
areas and awaiting documentation to fill those areas. Ha ha, there are 
already some functions with that style already. Sorry!

It would also standardize the comment style, unless the author replaces 
it completely, but it appears slightly confusing to have:

/**
 *
 */

Along with:

//
//

Along with:

/*
 *
 */

The standard is the first one and having the template would make that 
clear to those who wish to add documentation later.

2. Leaving parameter and return type information wouldn't make the 
documentation worth committing.

While the alternative is to give just the type and the variable name. I 
think leaving the area after blank means the same as {@internal Missing 
Description}} and it would be better to explicitly say that than to 
leave it implicit and assume that the reader understands that. Also, the 
reader might be more willing to fill out the information if the note is 
left there than if it wasn't. It would be how I would do it. However, 
adding it might just leave the reader saying "WTF? Why didn't they just 
fill it out?" Eh.

Really it is up to debate and why I would rather have all of the 
parameters and return information documented. That would mean that the 
short and long descriptions might have to be omitted, at least for now.


*Why I think the proposal is a good idea: Besides the arguments above.*

1. It would document every file purpose (in wp-includes/), so every 
function will be grouped with WordPress that belongs with WordPress and 
file level description will show up on xref sites as well as 
phpDocumentor sites.

2. It would show readers of the functions that an effort has been made 
and a standard is already in place for handling inline documentation. 
Which hopefully would keep another inline documentation discussion 
(about adding inline documentation and why there doesn't exist inline 
documentation/standard) from occurring 6 months to a year from now.

Any other reason why the proposed wouldn't be committed?

FYI Proposed template is as follows:

/**
 * function_name() - {@internal Missing Short Description}}
 *
 * {@internal Missing Long Description}}
 *
 * @since version
 * @uses information about what globals and functions the function uses.
 *
 * ... Parameters type/description and return type/description
 */

Also, I'm not proposing that someone do this, I'm already doing it. I 
just want to know if what I don't get finished will be committed when I 
stop documenting WordPress functions.

-- 

Jacob Santos

http://www.santosj.name - blog
http://wordpress.svn.dragonu.net/unittest/ - unofficial WP unit test suite.

Also known as darkdragon and santosj on WP trac.