2012/6/19 Michal Čihař michal@cihar.com:
Hi all, especially GSoC students
just a quick reminder, that docblocks are meant to document function and it's parameters, so writing docblocks as following is quite useless:
/** * * @param type $srid * @param type $scale_data * @param type $output */
- You should describe what the function is supposed to do
- You should document actual types of parameters instead of writing
there "type"
- You should document parameter meaning
Hi,
As an example of how the above example could be done (descriptions are fictional) :
/** * This summarized description briefly describes what this function does. * * This is a more elaborate description of what this function does, * going into detail about the inner workings and, if applicable, what * the influence is of the different parameters that are passed * to the function. * * @param int $srid ID of the element * @param array $scale_data array with data to be printed * @param string $output format of the returned output * * @return string formatted string of data objects */
Take note of the empty lines between summarized and full description, function parameters block and remaining tags block, and of outlining the description of the function parameters
You can check if the docblock is in the right format by using codesniffer (phpcs, more info on the wiki [0] on how to install and use it) or check the Checkstyle warnings for your file on our Jenkins server [1].
[0] http://wiki.phpmyadmin.net/pma/CodeSniffer [1] http://ci.phpmyadmin.net/