[wp-hackers] Proposal for a function commenting convention

[Jacob]

In a nutshell:

1. Should be include the "-bleeding", "-beta#", "-rc#" along with the 
version if applicable. I vote yes.
2. Do we concern ourselves with just wp-includes/*.php or with the 
entire function codebase, except for admin (unless you really want to).
3. What do we do with functions that we apply @since, @return, and 
@param too?
4. Since we are documenting functions, should we also document files 
(file level phpDoc), globals, and defines (thinking more of the wider 
context of having a phpdocumentor site).
5. Should we hold all functions in public namespace? I'm limiting some 
such as wp_unregister_GLOBALS() and setting it to private, meaning it 
shouldn't show up on any phpdocumentor site. Do we really need to fully 
document those functions, because no one should be using it. If it 
doesn't work, then it really needs to be unit tested to see if it is broken.

For #3:

I was thinking of boilerplate text:

/**
 * function_name() - Undocumented
 *
 * Undocumented
 *
 * @package Whatever
 * @subpackage WhateverSub
 * @since 1.5
 * @param if applicable
 * @return null Does not return anything or returns no explicit type.
 */

The "Undocumented" text would serve as a starting point for future 
documentation of procedural code. That is, it would give the reader a 
placeholder to document the function and submit the patch to trac. I 
think the simple functions are too easy to not fully document.

Jacob Santos

Jacob wrote:
> Matt wrote:
>> On 10/14/07, Jacob <wordpress at santosj.name> wrote:
>>  
>>> Question: Should the since be which one?
>>>
>>> 1. @since 1.5
>>> 2. @since WP 1.5
>>> 3. @since WordPress 1.5
>>> 4. @since Version 1.5
>>>
>>>     
>>
>> I like the 1st one better. It's shorter, and it gets to the point 
>> quicker.
>>
>>   
> I was thinking about contexts such as "2.3-bleeding" or "2.4-bleeding" 
> or "2.3-beta1" as the main concern is the completed working version 
> the function is going to exist. For testing purposes, does it mean 
> anything if you have the trunk version and the since is 2.4, but it 
> hasn't been release yet. Can you just assume that it the since is the 
> next version.
>
> What I mean, is that a user is going to download the release version, 
> which will be accurate to them, but not the plugin tester. Well, my 
> logic is flawed, because most normal users are not going to break open 
> the code and say, "Oh yeah, that is when that was added, I really 
> needed to know that."
>
> Henceforth, it would be a good idea to include the "-bleeding" to say 
> the function was released prior to beta and maybe include the SVN 
> revision number and for betas and release candidates, include "-beta#" 
> for beta and "-RC#" for release candidates.
>
> For the older releases, at least the patches I'm going to create, I'm 
> going off the completed releases and not worrying with -bleeding or 
> whatever. Tags are much much easier to go by for past releases.
>
> Do we also want to document every function or focus on just the 
> wp-includes? If we focus on just wp-includes, it would leave out 
> xmlrpc.php functions and class and perhaps some others. Then again, 
> the method I listed does not give you the file the function exists. It 
> also does not help if you have plugins installed.
>
> Jacob Santos
> _______________________________________________
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-hackers