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

Packaging assignment module for better documentation structure

    XMLWordPrintable

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Trivial
    • Resolution: Won't Fix
    • Affects Version/s: 1.9, 1.9.1, 1.9.2, 2.0
    • Fix Version/s: None
    • Component/s: Assignment (2.2), PHPDoc
    • Labels:
      None
    • Affected Branches:
      MOODLE_19_STABLE, MOODLE_20_STABLE

      Description

      Assignment 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-assignment
      • @category mod
      • @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)
        */

      /**

      • Defines and requires
        */

      Subplugins such as assignment types should have an additional @subpackage tag

      /**

      • file description
        *
      • @package mod-assignment
      • @category mod
      • @subpackage assignmenttype (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 blocks 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){
        }

      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 inthe phpdoc.

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

        Attachments

          Activity

            People

            Assignee:
            moodle.com moodle.com
            Reporter:
            vf Valery Fremaux
            Participants:
            Component watchers:
            Adrian Greeve, Jake Dallimore, Mathew May, Mihail Geshoski, Peter Dias, Amaia Anabitarte, Carlos Escobedo, Ferran Recio, Sara Arjona (@sarjona)
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Dates

              Created:
              Updated:
              Resolved: