Uploaded image for project: 'Moodle'
  1. Moodle
  2. MDL-15067

Forum module review of comments headers for better phpdocs documentation structure

    XMLWordPrintable

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Trivial
    • Resolution: Deferred
    • Affects Version/s: 1.9, 1.9.1, 1.9.2, 2.0
    • Fix Version/s: None
    • Component/s: Forum, PHPDoc
    • Labels:
    • Affected Branches:
      MOODLE_19_STABLE, MOODLE_20_STABLE

      Description

      Hi Martin !! your turn !!

      Forum as a core module should be reviewed for phpdoc generation correct packaging :

      all module root level php files should present a :

      /**

      • file description
      • @package mod-forum
      • @category mod
      • @author martin dougiamas (and others)
      • @contributors list of known contributors (optional)
      • @license http://www.gnu.org/copyleft/gpl.html GNU Public License (unless other licensing)
        */

      /**

      • Defines and requires
        */

      There are no subpackage concerns for forum
      If there are in other module, we try to resolve them as follows :

      Subplugins should have an additional @subpackage (e.g. assigmenttype) "or something like that" tag

      /**

      • file description
      • @package mod-assigment
      • @category mod
      • @subpackage assigmenttype (example)
      • @author initial author if known (optional)
      • @contributors list of known contributors (optional)
      • @license http://www.gnu.org/copyleft/gpl.html GNU Public License (unless other licensing)
        */

      If some code use MVC pattern, we have added an @usecase tag that could be used to list all handled use cases (UML meaning).

      These above docblocks MUST be first block of comment just under <?php opening line.

      If the first code construction that follows is a class or a function, it should have its own comment block.

      The form :

      function afunction($parm){
      /// some comments
      }

      should be deprecated, using phpblocks instead :

      /**

      • @param type $parm description
        */
        function afunction($parm){
        }

      Message for all people I added in other posts :

      Many thanks for helping improving documentation structure.

      Note1 : that all php files should be headed, not only lib ot locallib. This ensures all local function or structure defines will be correctly packed in the right phpdoc subsection.

      Note 2 : please all packaging should be at least commited for 1.9 and HEAD branches.

      Cheers.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              dobedobedoh Andrew Nicols
              Reporter:
              vf Valery Fremaux
              Participants:
              Component watchers:
              Andrew Nicols, Jun Pataleta, Michael Hawkins, Shamim Rezaie, Simey Lameze, Amaia Anabitarte, Carlos Escobedo, Ferran Recio, Ilya Tregubov, Sara Arjona (@sarjona)
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: