[wp-hackers] Proposal for a function commenting convention
wordpress at santosj.name
Sun Oct 14 08:18:35 GMT 2007
> 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.
More information about the wp-hackers