[Phpmyadmin-devel] Writing useful docblocks

[Dieter Adriaenssens]

2012/6/19 Michal Čihař <michal at 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/

-- 
Kind regards,

Dieter Adriaenssens