-
Type:
Improvement
-
Status: Resolved
-
Priority:
Minor
-
Resolution: Fixed
-
Affects Version/s: 1.9.11, 2.0.2, 2.2.1
-
Fix Version/s: 2.0.2
-
Component/s: = REQUESTING NEW COMPONENT HERE =, Module: HotPot
-
Labels:None
-
Affected Branches:MOODLE_19_STABLE, MOODLE_20_STABLE, MOODLE_22_STABLE
-
Fixed Branches:MOODLE_20_STABLE
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.