MDL-30998: updated docblocks for advanced grading

grade/grading/form/lib.php

@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -18,24 +17,41 @@
 /**
  * Common classes used by gradingform plugintypes are defined here
  *
- * @package    core
- * @subpackage grading
+ * @package    core_grading
  * @copyright  2011 David Mudrak <[email protected]>
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
 
 /**
- * Grading method controller represents a plugin used in a particular area
+ * Class represents a grading form definition used in a particular area
+ *
+ * General data about definition is stored in the standard DB table
+ * grading_definitions. A separate entry is created for each grading area
+ * (i.e. for each module). Plugins may define and use additional tables
+ * to store additional data about definitions.
+ *
+ * Advanced grading plugins must declare a class gradingform_xxxx_controller
+ * extending this class and put it in lib.php in the plugin folder.
+ *
+ * See {@link gradingform_rubric_controller} as an example
+ *
+ * Except for overwriting abstract functions, plugin developers may want
+ * to overwrite functions responsible for loading and saving of the
+ * definition to include additional data stored.
+ *
+ * @copyright  2011 David Mudrak <[email protected]>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @category   grading
  */
 abstract class gradingform_controller {
 
     /** undefined definition status */
     const DEFINITION_STATUS_NULL = 0;
     /** the form is currently being edited and is not ready for usage yet */
     const DEFINITION_STATUS_DRAFT = 10;
-    /** the for was marked as ready for actual usage */
+    /** the form was marked as ready for actual usage */
     const DEFINITION_STATUS_READY = 20;
 
     /** @var stdClass the context */
@@ -80,27 +96,35 @@ public function __construct(stdClass $context, $component, $area, $areaid) {
     }
 
     /**
+     * Returns controller context
+     *
      * @return stdClass controller context
      */
     public function get_context() {
         return $this->context;
     }
 
     /**
+     * Returns gradable component name
+     *
      * @return string gradable component name
      */
     public function get_component() {
         return $this->component;
     }
 
     /**
+     * Returns gradable area name
+     *
      * @return string gradable area name
      */
     public function get_area() {
         return $this->area;
     }
 
     /**
+     * Returns gradable area id
+     *
      * @return int gradable area id
      */
     public function get_areaid() {
@@ -366,7 +390,7 @@ public function get_current_instance($raterid, $itemid, $idonly = false) {
                 'status1'  => gradingform_instance::INSTANCE_STATUS_ACTIVE,
                 'status2'  => gradingform_instance::INSTANCE_STATUS_NEEDUPDATE);
         $select = 'definitionid=:definitionid and itemid=:itemid and (status=:status1 or status=:status2)';
-        if (false /* TODO $manager->allow_multiple_raters() */) {
+        if (false /* TODO MDL-31237 $manager->allow_multiple_raters() */) {
             $select .= ' and raterid=:raterid';
             $params['raterid'] = $raterid;
         }
@@ -543,7 +567,7 @@ public static function sql_search_where($token) {
         return array($subsql, $params);
     }
 
-    ////////////////////////////////////////////////////////////////////////////
+    // //////////////////////////////////////////////////////////////////////////
 
     /**
      * Loads the form definition if it exists
@@ -567,6 +591,8 @@ protected function load_definition() {
     abstract protected function delete_plugin_definition();
 
     /**
+     * Returns the name of the grading method plugin, eg 'rubric'
+     *
      * @return string the name of the grading method plugin, eg 'rubric'
      * @see PARAM_PLUGIN
      */
@@ -617,15 +643,39 @@ public final function get_grade_range() {
 }
 
 /**
- * Class to manage one grading instance. Stores information and performs actions like
- * update, copy, validate, submit, etc.
+ * Class to manage one gradingform instance.
+ *
+ * Gradingform instance is created for each evaluation of a student, using advanced grading.
+ * It is stored as an entry in the DB table gradingform_instance.
+ *
+ * One instance (usually the latest) has the status INSTANCE_STATUS_ACTIVE. Sometimes it may
+ * happen that a teacher wants to change the definition when some students have already been
+ * graded. In this case their instances change status to INSTANCE_STATUS_NEEDUPDATE.
+ *
+ * To support future use of AJAX for background saving of incomplete evaluations the
+ * status INSTANCE_STATUS_INCOMPLETE is introduced. If 'Cancel' is pressed this entry
+ * is deleted.
+ * When grade is updated the previous active instance receives status INSTANCE_STATUS_ACTIVE.
+ *
+ * Advanced grading plugins must declare a class gradingform_xxxx_instance
+ * extending this class and put it in lib.php in the plugin folder.
+ *
+ * The reference to an instance of this class is passed to an advanced grading form element
+ * included in the grading form, so this class must implement functions for rendering
+ * and validation of this form element. See {@link MoodleQuickForm_grading}
  *
  * @copyright  2011 Marina Glancy
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @category   grading
  */
 abstract class gradingform_instance {
+    /** Valid istance status */
     const INSTANCE_STATUS_ACTIVE = 1;
+    /** The grade needs to be updated by grader (usually because of changes is grading method) */
     const INSTANCE_STATUS_NEEDUPDATE = 2;
+    /** The grader started grading but did clicked neither submit nor cancel */
     const INSTANCE_STATUS_INCOMPLETE = 0;
+    /** Grader re-graded the student and this is the status for previous grade stored as history */
     const INSTANCE_STATUS_ARCHIVE = 3;
 
     /** @var stdClass record from table grading_instances */
@@ -768,8 +818,7 @@ protected function make_active() {
      */
     public function cancel() {
         global $DB;
-        // TODO what if we happen delete the ACTIVE instance, shall we rollback to the last ARCHIVE? or throw an exception?
-        // TODO create cleanup cron
+        // TODO MDL-31239 throw exception if status is not INSTANCE_STATUS_INCOMPLETE
         $DB->delete_records('grading_instances', array('id' => $this->get_id()));
     }
 
@@ -788,7 +837,7 @@ public function update($elementvalue) {
         if (isset($elementvalue['itemid']) && $elementvalue['itemid'] != $this->data->itemid) {
             $newdata->itemid = $elementvalue['itemid'];
         }
-        // TODO also update: rawgrade, feedback, feedbackformat
+        // TODO MDL-31087 also update: rawgrade, feedback, feedbackformat
         $DB->update_record('grading_instances', $newdata);
         foreach ($newdata as $key => $value) {
             $this->data->$key = $value;
@@ -873,6 +922,9 @@ public function validate_grading_element($elementvalue) {
      * If plugin wants to display custom message, the empty string should be returned here
      * and the custom message should be output in render_grading_element()
      *
+     * Please note that in assignments grading in 2.2 the grading form is not validated
+     * properly and this message is not being displayed.
+     *
      * @see validate_grading_element()
      * @return string
      */

grade/grading/form/rubric/backup/moodle2/backup_gradingform_rubric_plugin.class.php

@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -18,8 +17,7 @@
 /**
  * Support for backup API
  *
- * @package    gradingform
- * @subpackage rubric
+ * @package    gradingform_rubric
  * @copyright  2011 David Mudrak <[email protected]>
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -28,6 +26,9 @@
 
 /**
  * Defines rubric backup structures
+ *
+ * @copyright  2011 David Mudrak <[email protected]>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class backup_gradingform_rubric_plugin extends backup_gradingform_plugin {
 

grade/grading/form/rubric/backup/moodle2/restore_gradingform_rubric_plugin.class.php

@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -18,8 +17,7 @@
 /**
  * Support for restore API
  *
- * @package    gradingform
- * @subpackage rubric
+ * @package    gradingform_rubric
  * @copyright  2011 David Mudrak <[email protected]>
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -28,6 +26,9 @@
 
 /**
  * Restores the rubric specific data from grading.xml file
+ *
+ * @copyright  2011 David Mudrak <[email protected]>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class restore_gradingform_rubric_plugin extends restore_gradingform_plugin {
 
@@ -69,6 +70,8 @@ protected function define_instance_plugin_structure() {
      *
      * Sets the mapping 'gradingform_rubric_criterion' to be used later by
      * {@link self::process_gradinform_rubric_filling()}
+     *
+     * @param stdClass|array $data
      */
     public function process_gradingform_rubric_criterion($data) {
         global $DB;
@@ -86,6 +89,8 @@ public function process_gradingform_rubric_criterion($data) {
      *
      * Sets the mapping 'gradingform_rubric_level' to be used later by
      * {@link self::process_gradinform_rubric_filling()}
+     *
+     * @param stdClass|array $data
      */
     public function process_gradingform_rubric_level($data) {
         global $DB;
@@ -100,6 +105,8 @@ public function process_gradingform_rubric_level($data) {
 
     /**
      * Processes filling element data
+     *
+     * @param stdClass|array $data
      */
     public function process_gradinform_rubric_filling($data) {
         global $DB;

grade/grading/form/rubric/db/upgrade.php

@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -16,8 +15,9 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * @package    gradingform
- * @subpackage rubric
+ * This file keeps track of upgrades to plugin gradingform_rubric
+ *
+ * @package    gradingform_rubric
  * @copyright  2011 David Mudrak <[email protected]>
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */

grade/grading/form/rubric/edit.php

@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -18,8 +17,7 @@
 /**
  * Rubric editor page
  *
- * @package    gradingform
- * @subpackage rubric
+ * @package    gradingform_rubric
  * @copyright  2011 Marina Glancy
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */

grade/grading/form/rubric/edit_form.php

@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -18,8 +17,7 @@
 /**
  * The form used at the rubric editor page is defined here
  *
- * @package    gradingform
- * @subpackage rubric
+ * @package    gradingform_rubric
  * @copyright  2011 Marina Glancy <[email protected]>
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -32,6 +30,9 @@
 
 /**
  * Defines the rubric edit form
+ *
+ * @copyright  2011 Marina Glancy <[email protected]>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class gradingform_rubric_editrubric extends moodleform {
 
@@ -65,7 +66,6 @@ public function definition() {
         // rubric editor
         $element = $form->addElement('rubriceditor', 'rubric', get_string('rubric', 'gradingform_rubric'));
         $form->setType('rubric', PARAM_RAW);
-        //$element->freeze(); // TODO freeze rubric editor if needed
 
         $buttonarray = array();
         $buttonarray[] = &$form->createElement('submit', 'saverubric', get_string('saverubric', 'gradingform_rubric'));
@@ -175,7 +175,7 @@ public function need_confirm_regrading($controller) {
         }
 
         // freeze form elements and pass the values in hidden fields
-        // TODO description_editor does not freeze the normal way!
+        // TODO MDL-29421 description_editor does not freeze the normal way, uncomment below when fixed
         $form = $this->_form;
         foreach (array('rubric', 'name'/*, 'description_editor'*/) as $fieldname) {
             $el =& $form->getElement($fieldname);

grade/grading/form/rubric/lang/en/gradingform_rubric.php

@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -16,8 +15,9 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * @package    gradingform
- * @subpackage rubric
+ * Language file for plugin gradingform_rubric
+ *
+ * @package    gradingform_rubric
  * @copyright  2011 David Mudrak <[email protected]>
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */