[wp-hackers] Proposal for a function commenting convention

[Jacob]

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'm using #1 since it is the easiest. #3 might be useful if WordPress Mu 
ever jumps on board and does the same for its functions. However, it 
could just use @package or @category to distinguish its version from 
WordPress version. Or you could just have @category WordPress. However, 
I believe versions of phpDocumentor do not use @category for rendering 
the documentation HTML pages.

In shutdown_action_hook(), which a little humorous because that function 
is a @since 1.5 function.

{
$arrFunctionList = 
<http://us3.php.net/manual/en/function.get-defined-functions.php>get_defined_functions();
foreach($arrFunctionList['user'] as $strFunctionName)
{
    echo "$strFunctionName<br />\n";
}
}

Really does wonders, but I'm setting it up for trunk and doing a massive 
find to get the declaration in trunk version. Some classes and functions 
don't exist in trunk. I'm not doing this for admin files, because I 
enjoy little is left of my sanity.

Using this sort of grep method, you should be able to get all of the 
functions that are used in the tagged versions in the repository. Grep 
might be useful, but since I'm a Windows user, I don't have that easily 
functionality. Windows Search just isn't that elegant with these types 
of searches.

Jacob Santos


Jacob wrote:
> Err, yeah. Have you any thoughts of how the version which functions 
> were added are going to be found? I'm not even sure the devs would 
> know about every function. You'll find that checking repository log is 
> neat for files, but doesn't really tell you much about functions. 
> Unless of course you check each repository commit.
>
> (After some contemplation, one could perhaps, download or find an old 
> 1.5 version and just start from there. Use the 1.5 version and just 
> say that any and all functions that existed in that version started 
> with that version and ignore the previous versions.)