[wp-hackers] Proposal for a function commenting convention

[Jacob]

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.

Jacob Santos

Ryan Boren wrote:
> On 10/15/07, Robin Adrianse <robin.adr at gmail.com> wrote:
>   
>> +1.
>>
>> On 10/15/07, Otto <otto at ottodestruct.com> wrote:
>>     
>>> On 10/14/07, Jacob <wordpress at santosj.name> wrote:
>>>       
>>>> /**
>>>>  * @since 1.5
>>>>  * @deprecated since 2.1
>>>>  */
>>>>         
>>> I suggest using the same scheme for version numbers on both of these.
>>> In other words, do this instead:
>>> /**
>>> * @since 1.5
>>> * @deprecated 2.1
>>> */
>>>       
>
> +1 here too.
>
> Also, we have some old phpdoc patches around if anyone wants to update them.
>
> http://trac.wordpress.org/query?status=new&status=assigned&status=reopened&status=closed&keywords=%7Ephpdoc&order=priority
> _______________________________________________
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-hackers
>