Moodle 3.x Developer's Guide

Describing functions and methods

All functions should be commented with a docblock, even if it is immediately obvious what the function does (what might be obvious to you might not necessarily be obvious to the next person).

All functions and methods should have a complete docblock like this:

/**  * Give a description of the function - clearly stating what the purpose  * of the function is, even if you think it is obvious. To refer to another   * function use @see. To link to documentation on the web  * use a @link below. Also, remember to add descriptions   * for parameters and the return value. Make variable names obvious, too.  *  * @see clean_param()  * @param int   $courseid The PHP type is followed by the variable name  * @param array ...