GNOME Bugzilla – Bug 613185
PHP datatype in de @param
Last modified: 2011-04-11 18:29:50 UTC
The generator gives out these errors: ======================================================================= Graph.inc:89: Warning: argument 'integer' of command @param is not found in the argument list of Graph::__construct($width,$height,$dpi,$decimalSeperator,$thousandsSeperator) Graph.inc:89: Warning: argument 'integer' of command @param is not found in the argument list of Graph::__construct($width,$height,$dpi,$decimalSeperator,$thousandsSeperator) Graph.inc:89: Warning: argument 'integer' of command @param is not found in the argument list of Graph::__construct($width,$height,$dpi,$decimalSeperator,$thousandsSeperator) Graph.inc:89: Warning: argument 'string' of command @param is not found in the argument list of Graph::__construct($width,$height,$dpi,$decimalSeperator,$thousandsSeperator) Graph.inc:89: Warning: argument 'string' of command @param is not found in the argument list of Graph::__construct($width,$height,$dpi,$decimalSeperator,$thousandsSeperator) Graph.inc:89: Warning: The following parameters of Graph::__construct($width,$height,$dpi,$decimalSeperator,$thousandsSeperator) are not documented: parameter 'width' parameter 'height' parameter 'dpi' parameter 'decimalSeperator' parameter 'thousandsSeperator' ======================================================================= The corresponding code is: ======================================================================= /** * Graph::__construct() * * @param integer $width * @param integer $height * @param integer $dpi * @param string $decimalSeperator * @param string $thousandsSeperator * @return */ function __construct($width, $height, $dpi, $decimalSeperator, $thousandsSeperator){} ======================================================================= PHP is not strongly typed. So types should be specified in the documentation. Other php documentation systems support this. And the output of Doxygen seems also to support it. The parameter types are mentioned correctly. Then why these errors are given? And also why doesn't the documentation mention the posibility of adding the datatype. I'm now not sure whether it is or isn't supported...I would be nice if it is because then the source code would be compatible with other documentation systems some of our clients might use. The generated output: ======================================================================= Graph::__construct ( $ width, $ height, $ dpi, $ decimalSeperator, $ thousandsSeperator ) Graph::__construct(). Parameters: integer $width integer $height integer $dpi string $decimalSeperator string $thousandsSeperator =======================================================================
The type argument is not support at the moment. For PHP I could use the fact the parameter names start with a $ (is this always the case?). Then a @param matching @param datatype $varname Description. could be distinguished from @param varname Description for other languages. An alternative would be to use @param[type] $varname Description which would also be useful for other scripting languages that do not have the $. I noticed, some PHP documentation tools also support @param datatype1|datatype2 $varname Description. which could be useful for mixed types.
+1 for @param datatype1|datatype2 $varname Description.
$ before a variable name is always the case for PHP, but e.g. for Perl $, % and @ would be valid prefixes, and in Ruby or Python we have no sigil at all. The following @param[type1|type2|typeN...] varname Description seems like a good option to me (with varname including $, %, @ or whatever other sigil is supported), as it could be adapted for other scripting languages as well.
Note that in the meantime support for types has been added to @param (at least for PHP). See http://www.doxygen.org/commands.html#cmdparam for more details. So I'm closing this bug report. If you see any issues feel free to reopen this report and add additional information.