On Thu, Apr 26, 2012 at 8:52 AM, Jeremy Postlethwaite < [email protected]> 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_Documentation > > 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 [email protected] _______________________________________________ Wikitech-l mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/wikitech-l
