Uploaded image for project: 'Moodle Community Sites'
  1. Moodle Community Sites
  2. MDLSITE-2804

file/class phpdoc blocks clarification, policy and tool fixing

    XMLWordPrintable

    Details

      Description

      Policy: PHPDoc file/class policy cleanup

      Since 27th Nov 2020, these changes have been performed:

      Documentation and comments > Classes

      /**
       * 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 {
      

      • For files containing only one artifact (class, interface, trait...) and nothing else (specifically, all the files within classes directories, but also artifacts 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 the optional @category tag ), as shown in the example above, must be present always in the file (in whichever docblock, but all together).

      Note: It's NOT required to change all current old-style occurrences in the codebase. We'll follow a progressive approach here (new code and modified code).

      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.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              stronk7 Eloy Lafuente (stronk7)
              Reporter:
              timhunt Tim Hunt
              Participants:
              Component watchers:
              Marina Glancy, Eloy Lafuente (stronk7), Eloy Lafuente (stronk7)
              Votes:
              1 Vote for this issue
              Watchers:
              7 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: