[wp-hackers] Proposal for a function commenting convention

[Jacob]

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.)

Good luck with that. I would advise against trying it, because I can see 
into the future and I can tell you straight up and right now that you're 
not going to get very far before you give up. I know I would and you 
would have to be completely diehard and god-like to do so. Meaning that 
if you were to complete such a task, I would build a shine in your honor.

I think that going forward, it would be a good idea. Going back and 
adding @since isn't going to do any good, since well, plugin authors 
already know that their plugins don't work.

Besides that. I think that if you were (and by you, I mean we) going to 
add phpDoc comments, it should also include information about the 
function. What the function does and what it is used for and how in the 
code is more useful than @since (not that I'm saying @since is useless, 
because it isn't, it is more useful for future documentation than past).

In which case, I agree that the convention should be

/**
 * function_name() - Short description
 *
 * Long Description
 *
 * @param Stuff here
 * @return Stuff here
 * @since Version here (if known. Taxonomy should be updated to include 
@since 2.3)
 */

The reason for this convention is that the first thing a person wants to 
know is what the function purpose is without the filler crap. The second 
thing a coder wants to know after they've decided upon that, is more 
about what it does and how to use it. If you are really hardcore, you'll 
add (@example Code) or (@tutorial Text ... Code).

Meaning, while the "function_name()" portion is redundant in the 
phpDocumentor context, it is still useful for the reader browsing the 
code. You don't have to keep scrolling down to see what the function is, 
it is just right there at the top!

I did some work on the Taxonomy documentation. I would like very much if 
someone else would work on that. In that case, would it be neat if we 
picked a file and assigned functions to whoever wants them to write 
documentation for it? I'll be more willing to take up the task, if I 
knew others were undergoing the same torture I was.

Cheers,

Jacob Santos

Jared Bangs wrote:
> On 10/13/07, Ozh <ozh at planetozh.com> wrote:
>   
>> On 10/13/07, Robin Adrianse <robin.adr at gmail.com> wrote:
>>     
>>> PHPDoc has a @since variable, which was made specifically for this
>>>       
>> purpose.
>>
>> But I'd really like at least a simple "// added in WP 2.4" even for
>> basic non phpdoc'ed stuff :)
>>     
>
>
> +1 for using PHPDoc as a standard way of doing this. If we're going to go
> back through and add comments to the existing code, it should definitely be
> in a consistent format.
> _______________________________________________
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-hackers
>