/**

 * Short description for class.

 *

 * Long description for class (if any)...

 *

 * @package    mod_mymodule

 * @category   backup

 * @copyright  2008 Kim Bloggs

 * @license    https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

class policy_issue {

We have a rule that if a file has only one class, you don't need both a file comment and a class comment. However, CiBoT complains if you do that.

Right now, the coding style says:

All classes must have a complete docblock like this:
....

The exception are files containing only one class and nothing else. In that case the class is covered by the file docblock and adding an explicit class docblock is optional to any extent (you can decide to add it, or not at all, or only add one or both descriptions, with or without @copyright/@license...).

This issue is about to try to clarify this a step further, prioritizing class docs over file ones when possible and, of course, make local_moodlecheck compliant.

The proposal is to change the above to:

All classes must have a complete docblock like this:

/**

* Short description for class.

*

* Long description for class (if any)...

*

* @package mod_mymodule

* @copyright 2008 Kim Bloggs

* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

*/

class policy_issue {

For files containing only one class and nothing else (specifically, all the files within classes directories, but also classes fulfilling the condition anywhere else) it will be enough with the class phpdoc block. The file phpdoc block will be considered optional at all effects, giving to the class one precedence.

The @package, @copyright and @license tags (and optional @category tag), as shown in the example above, must be present always in the file (in whichever docblock, but all together).

Of course, in parallel, we'll edit the files phpdoc section to express the new "optional" nature of the phpdoc for 1-class files.

So, options basically are (summary of the above):

-1) Keep things as they are: File docblocks have precedence.
+1) Let's prioritise class docblocks (mandatory) over file docblocks (optional) in 1-class files. The format and all mandatory tags will continue being the same (@package, @copyright and @license), with optional @category.

Process:

• Make the proposal official.
• Vote.
• Amend coding style.
• Enforce coding style.