[wp-hackers] Proposal for a function commenting convention

[Jacob]

Travis Snoozy wrote:
> On Tue, 16 Oct 2007 09:03:21 +0100 (BST), "Peter Westwood"
> <peter.westwood at ftwr.co.uk> wrote:
>
>   
>> On Tue, October 16, 2007 1:51 am, Jacob wrote:
>>     
>>> Agreed. I'll update the patches.
>>>
>>> I have some more questions.
>>>
>>> I think a compromise between Travis and me would be that we include
>>> both what functions should do along with what it does do. This will
>>> give optimal information on what to expect in both what the
>>> function does and what it actually does. In going over the
>>> plugins.php phpdoc, I did just this. I found that using the @see
>>> http://trac.wordpress.org/ticket/{Ticket number of bug} in that, in
>>> the likely chance that the bug is fixed, the reader would know by
>>> looking at the trac ticket.
>>>
>>> The second is that I haven't reached a conclusion on short
>>> description format.
>>>
>>> /**
>>>  * function_name() - short description
>>>
>>> or
>>>
>>> /**
>>>  * short description
>>>
>>> Plugins.php uses the second, while taxonomy.php (the phpdoc that I
>>> wrote) uses the first.
>>>
>>>       
>> My vote would be for the first - Adding the function_name() as well
>> feels like unnecessary duplication.
>>     
>
> Theoretically, I concur with you. In practice, I find that having the
> function name is really useful when reading these comments in the
> source, especially if the comments are more than a screen worth of text.
> Even when I can see the function line, I wind up scanning down and up
> to match the documentation with the function name, and it tends to
> break my flow of focus. Naturally, this is only an issue when reading
> the comments in-line with the code -- but again, in practice, that's
> where I usually read these.
>
>
>   
Compelling and I agree with you, but it is really a matter of preference 
and I don't want to say, "This is how it will be done." If plugins.php 
did not have the second, then it wouldn't be an issue. I do not feel 
that updating those parts to the first is in my rights. I do think that 
if anything, this should be a standard and followed through for all 
function phpdoc. In which case, any future phpdoc comments should not be 
in confusion of which style to use. If someone sees that it is one style 
or the other, then that is most likely what they will use.

The reason to not use the first (I really should have numbered the 
methods) is because the phpDocumentor site for WordPress is already 
going to have that information. While in the source code it would be 
useful, it wouldn't for use phpDocumentor. Now you could do something like:

#3
/**
 * @internal       function_name();
 * @access public
 *
 * Short Description
 *
 * Long Description

This would solve both issues of become confused of which function you 
are looking at and it wouldn't show up in the phpDocumentor site. The 
@access public line should block the @internal from hiding the short 
description and long description text. You would just have to be 
explicit on whether the function is public or private.

I think the goal should be to shoot for being able to have a complete 
phpDocumentor site for WordPress functions. I do think it will take a 
long time to fully document all functions.

Whichever method make sense. If no one has any objections, then I will 
upload the second patch [1] that uses the first style. If anything, 
changing plugins.php will be justified by, "Well, all of the /other/ 
files are doing it." I would have suggested that a massive change be 
applied that "fixes" the issue either way, but from reading past phpdoc 
efforts, it seems that patches must be for one file.

I stripped out the @license tag, since it really isn't my place to place 
that requirement and WordPress is well known enough that almost everyone 
knows WordPress is GPL. It really isn't that important and if the issue 
ever does become decided, then it can always be added later.

My priority with documenting WordPress code is whatever I feel like and 
"fixing" existing files that have patches. I also feel compelled to 
complete taxonomy.php phpdoc, since I keep thinking back to it and how 
it isn't complete and how awesome it would be if it was only complete. I 
won't trend on anyone's feet if they take up the effort of any file. 
Unless you don't feel up the task of documenting one of more functions 
within that file.

Also, at the very least, the @param, @global, @return, @since needs to 
be added to every file and that is the easiest part. The short and long 
description can come later, I think, as people feel compelled to 
complete them, "WTF? This function isn't fully documented and I spent 
hours trying to figure it out. I might as well tell others about it, so 
they don't spend the same amount as I have." Perhaps, I'm an optimist, 
but documentation is boring, except in this case where it is a group effort.

[1] http://trac.wordpress.org/ticket/5211

Jacob Santos