Uploaded image for project: 'Plugins'
  1. Plugins
  2. CONTRIB-3446

Packaging hotpot module for better phpdocs documentation structure

    XMLWordPrintable

    Details

    • Affected Branches:
      MOODLE_19_STABLE, MOODLE_20_STABLE, MOODLE_22_STABLE
    • Fixed Branches:
      MOODLE_20_STABLE

      Description

      Hotpot 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-hotpot
      • @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 hotpot reports types should have an additional @subpackage hotpotreports or something like that tag

      /**

      • file description
      • @package mod-hotpot
      • @category mod
      • @subpackage hotpotreport (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){
        }

      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.

        Attachments

          Activity

            People

            • Assignee:
              xxxxxxx Gordon Bateson
              Reporter:
              vf Valery Fremaux
              Participants:
              Component watchers:
              Anthony Borrow, Gordon Bateson
            • Votes:
              1 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:
                Fix Release Date:
                21/Feb/11