On Thu, Apr 26, 2012 at 8:52 AM, Jeremy Postlethwaite <
jpostlethwaite(a)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_Do…
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>
:
@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
--
Andrew Garrett
Wikimedia Foundation
agarrett(a)wikimedia.org