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

Packaging assignment module for better documentation structure

    XMLWordPrintable

Details

    • Improvement
    • Status: Closed
    • Trivial
    • Resolution: Won't Fix
    • 1.9, 1.9.1, 1.9.2, 2.0
    • None
    • Assignment (2.2), PHPDoc
    • None
    • 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

            moodle.com moodle.com
            vf Valery Fremaux
            Adrian Greeve, Jake Dallimore, Mathew May, Mihail Geshoski, Sujith Haridasan, 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: