[wp-hackers] Proposal for a function commenting convention

[Peter Westwood]

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.

westi
-- 
Peter Westwood <peter.westwood at ftwr.co.uk>
http://blog.ftwr.co.uk