On Thu, Apr 26, 2012 at 8:52 AM, Jeremy Postlethwaite < jpostlethwaite@wikimedia.org> wrote:
Hello!
In the Mediawiki coding conventions section on PHP, the format for @param tag is not what Doxygen recommends.
http://www.mediawiki.org/wiki/Manual:Coding_conventions/PHP#Comments_and_Doc...
We have:
General format for parameters is such: @param $varname [type]: [description]. Multiple types can be listed by separating with a pipe character.
I added a note in the document:
Doxygen documentation states that @param should have the same format as phpDocumentor[1]< http://www.mediawiki.org/wiki/Manual:Coding_conventions/PHP#cite_note-0%3E :
@param datatype1|datatype2 $paramname description
How should we deal with this?
Unlike Java, which doxygen was originally developed for, PHP is a weakly typed language. Often, a function parameter can take multiple types.
So actually, I'd be in favour of the status quo, which is to specify the type as part of the description.
So instead of: @param $title Title Title for the method or @param Title $title Title for the method.
We should use: @param $title Title object to use for the method.
—Andrew