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

Forum module review of comments headers for better phpdocs documentation structure

    XMLWordPrintable

Details

    • Improvement
    • Status: Closed
    • Trivial
    • Resolution: Deferred
    • 1.9, 1.9.1, 1.9.2, 2.0
    • None
    • Forum, PHPDoc
    • 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

              dobedobedoh Andrew Lyons
              vf Valery Fremaux
              Andrew Lyons, Huong Nguyen, Jun Pataleta, Michael Hawkins, Shamim Rezaie, Simey Lameze, Amaia Anabitarte, Carlos Escobedo, Ferran Recio, Ilya Tregubov, Laurent David, Sara Arjona (@sarjona)
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: