[wp-hackers] Proposal for a function commenting convention

[Jacob]

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