[wp-hackers] Proposal for a function commenting convention

Peter Westwood peter.westwood at ftwr.co.uk
Tue Oct 16 08:03:21 GMT 2007

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.

Peter Westwood <peter.westwood at ftwr.co.uk>

More information about the wp-hackers mailing list