Tidied up the PHPDocs and set the base element to an abstract class

edit_element_form.php

@@ -45,7 +45,7 @@ class mod_customcert_edit_element_form extends moodleform {
 
         $element = $this->_customdata['element'];
 
-        // Add the field for the name of the variable, this is required for all elements.
+        // Add the field for the name of the element, this is required for all elements.
         $mform->addElement('text', 'name', get_string('elementname', 'customcert'));
         $mform->setType('name', PARAM_TEXT);
         $mform->setDefault('name', get_string('pluginname', 'customcertelements_' . $element->element));
@@ -68,8 +68,8 @@ class mod_customcert_edit_element_form extends moodleform {
     /**
      * Validation.
      *
-     * @param $data
+     * @param array $data
-     * @param $files
+     * @param array $files
      * @return array the errors that were found
      */
     public function validation($data, $files) {

elements/code/lib.php

@@ -15,24 +15,23 @@
 // You should have received a copy of the GNU General Public License
 // along with Moodle. If not, see <http://www.gnu.org/licenses/>.
 
+defined('MOODLE_INTERNAL') || die('Direct access to this script is forbidden.');
+
+require_once($CFG->dirroot . '/mod/customcert/elements/element.class.php');
+
 /**
- * The code elements core interaction API.
+ * The customcert element code's core interaction API.
  *
  * @package    customcertelements_code
  * @copyright  Mark Nelson <markn@moodle.com>
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
-
-defined('MOODLE_INTERNAL') || die('Direct access to this script is forbidden.');
-
-require_once($CFG->dirroot . '/mod/customcert/elements/element.class.php');
-
 class customcert_elements_code extends customcert_elements_base {
 
     /**
      * Handles rendering the element on the pdf.
      *
-     * @param stdClass $pdf the pdf object
+     * @param pdf $pdf the pdf object
      */
     public function render($pdf) {
         global $DB, $USER;

elements/date/lib.php

@@ -15,19 +15,18 @@
 // You should have received a copy of the GNU General Public License
 // along with Moodle. If not, see <http://www.gnu.org/licenses/>.
 
-/**
- * The date elements core interaction API.
- *
- * @package    customcertelements_date
- * @copyright  Mark Nelson <markn@moodle.com>
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- */
-
 defined('MOODLE_INTERNAL') || die('Direct access to this script is forbidden.');
 
 require_once($CFG->dirroot . '/mod/customcert/elements/element.class.php');
 require_once($CFG->dirroot . '/mod/customcert/elements/grade/lib.php');
 
+/**
+ * The customcert element date's core interaction API.
+ *
+ * @package    customcertelements_date
+ * @copyright  Mark Nelson <markn@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class customcert_elements_date extends customcert_elements_base {
 
     /**
@@ -55,7 +54,7 @@ class customcert_elements_date extends customcert_elements_base {
     /**
      * This function renders the form elements when adding a customcert element.
      *
-     * @param stdClass $mform the edit_form instance.
+     * @param mod_customcert_edit_element_form $mform the edit_form instance
      */
     public function render_form_elements($mform) {
         // Get the possible date options.
@@ -77,7 +76,7 @@ class customcert_elements_date extends customcert_elements_base {
      * This will handle how form data will be saved into the data column in the
      * customcert_elements table.
      *
-     * @param stdClass $data the form data.
+     * @param stdClass $data the form data
      * @return string the json encoded array
      */
     public function save_unique_data($data) {
@@ -94,7 +93,7 @@ class customcert_elements_date extends customcert_elements_base {
     /**
      * Handles rendering the element on the pdf.
      *
-     * @param stdClass $pdf the pdf object
+     * @param pdf $pdf the pdf object
      */
     public function render($pdf) {
         // TO DO.

elements/element.class.php

@@ -27,7 +27,12 @@ require_once($CFG->dirroot . '/mod/customcert/includes/tcpdf_colors.php');
 
 defined('MOODLE_INTERNAL') || die('Direct access to this script is forbidden.');
 
-class customcert_elements_base {
+/**
+ * Class customcert_elements_base
+ *
+ * All customercert element plugins are based on this class.
+ */
+abstract class customcert_elements_base {
 
     /**
      * The data for the element we are adding.
@@ -47,7 +52,7 @@ class customcert_elements_base {
      * This function renders the form elements when adding a customcert element.
      * Can be overridden if more functionality is needed.
      *
-     * @param stdClass $mform the edit_form instance.
+     * @param mod_customcert_edit_element_form $mform the edit_form instance.
      */
     public function render_form_elements($mform) {
         // Render the common elements.
@@ -60,7 +65,7 @@ class customcert_elements_base {
      * Sets the data on the form when editing an element.
      * Can be overridden if more functionality is needed.
      *
-     * @param stdClass $mform the edit_form instance
+     * @param mod_customcert_edit_element_form $mform the edit_form instance
      * @param array the form elements to set
      */
     public function definition_after_data($mform) {
@@ -166,7 +171,7 @@ class customcert_elements_base {
      * Handles rendering the element on the pdf.
      * Must be overridden.
      *
-     * @param stdClass $pdf the pdf object
+     * @param pdf $pdf the pdf object
      */
     public function render($pdf) {
         // Must be overridden.
@@ -175,7 +180,7 @@ class customcert_elements_base {
     /**
      * Common behaviour for rendering specified content on the pdf.
      *
-     * @param stdClass $pdf the pdf object
+     * @param pdf $pdf the pdf object
      * @param string $content the content to render
      */
     public function render_content($pdf, $content) {
@@ -224,7 +229,7 @@ class customcert_elements_base {
     /**
      * Helper function to render the font elements.
      *
-     * @param stdClass $mform the edit_form instance.
+     * @param mod_customcert_edit_element_form $mform the edit_form instance.
      */
     public function render_form_elements_font($mform) {
         $mform->addElement('select', 'font', get_string('font', 'customcert'), customcert_get_fonts());
@@ -241,7 +246,7 @@ class customcert_elements_base {
     /**
      * Helper function to render the colour elements.
      *
-     * @param stdClass $mform the edit_form instance.
+     * @param mod_customcert_edit_element_form $mform the edit_form instance.
      */
     public function render_form_elements_colour($mform) {
         $mform->addElement('customcert_colourpicker', 'colour', get_string('fontcolour', 'customcert'));
@@ -253,7 +258,7 @@ class customcert_elements_base {
     /**
      * Helper function to render the position elements.
      *
-     * @param stdClass $mform the edit_form instance.
+     * @param mod_customcert_edit_element_form $mform the edit_form instance.
      */
     public function render_form_elements_position($mform) {
         $mform->addElement('text', 'posx', get_string('posx', 'customcert'), array('size' => 10));
@@ -309,7 +314,7 @@ class customcert_elements_base {
     /**
      * Sets the font for the element.
      *
-     * @param stdClass $pdf the pdf object
+     * @param pdf $pdf the pdf object
      */
     public function set_font($pdf) {
         // Variable for the font.

elements/grade/lib.php

@@ -15,14 +15,6 @@
 // You should have received a copy of the GNU General Public License
 // along with Moodle. If not, see <http://www.gnu.org/licenses/>.
 
-/**
- * The grade elements core interaction API.
- *
- * @package    customcertelements_grade
- * @copyright  Mark Nelson <markn@moodle.com>
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- */
-
 defined('MOODLE_INTERNAL') || die('Direct access to this script is forbidden.');
 
 require_once($CFG->dirroot . '/mod/customcert/elements/element.class.php');
@@ -35,6 +27,13 @@ require_once($CFG->dirroot . '/grade/querylib.php');
  */
 define('CUSTOMCERT_GRADE_COURSE', '0');
 
+/**
+ * The customcert element grade's core interaction API.
+ *
+ * @package    customcertelements_grade
+ * @copyright  Mark Nelson <markn@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class customcert_elements_grade extends customcert_elements_base {
 
     /**
@@ -62,7 +61,7 @@ class customcert_elements_grade extends customcert_elements_base {
     /**
      * This function renders the form elements when adding a customcert element.
      *
-     * @param stdClass $mform the edit_form instance.
+     * @param mod_customcert_edit_element_form $mform the edit_form instance
      */
     public function render_form_elements($mform) {
         // Get the grade items we can display.
@@ -105,7 +104,7 @@ class customcert_elements_grade extends customcert_elements_base {
     /**
      * Handles rendering the element on the pdf.
      *
-     * @param stdClass $pdf the pdf object
+     * @param pdf $pdf the pdf object
      */
     public function render($pdf) {
         global $USER;

elements/image/lib.php

@@ -15,18 +15,17 @@
 // You should have received a copy of the GNU General Public License
 // along with Moodle. If not, see <http://www.gnu.org/licenses/>.
 
+defined('MOODLE_INTERNAL') || die('Direct access to this script is forbidden.');
+
+require_once($CFG->dirroot . '/mod/customcert/elements/element.class.php');
+
 /**
- * The image elements core interaction API.
+ * The customcert element image's core interaction API.
  *
  * @package    customcertelements_image
  * @copyright  Mark Nelson <markn@moodle.com>
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
-
-defined('MOODLE_INTERNAL') || die('Direct access to this script is forbidden.');
-
-require_once($CFG->dirroot . '/mod/customcert/elements/element.class.php');
-
 class customcert_elements_image extends customcert_elements_base {
 
     /**
@@ -58,7 +57,7 @@ class customcert_elements_image extends customcert_elements_base {
     /**
      * This function renders the form elements when adding a customcert element.
      *
-     * @param stdClass $mform the edit_form instance.
+     * @param mod_customcert_edit_element_form $mform the edit_form instance
      */
     public function render_form_elements($mform) {
         $mform->addElement('select', 'image', get_string('image', 'customcertelements_image'), self::get_images());
@@ -105,7 +104,7 @@ class customcert_elements_image extends customcert_elements_base {
      * This will handle how form data will be saved into the data column in the
      * customcert_elements table.
      *
-     * @param stdClass $data the form data.
+     * @param stdClass $data the form data
      * @return string the json encoded array
      */
     public function save_unique_data($data) {
@@ -122,7 +121,7 @@ class customcert_elements_image extends customcert_elements_base {
     /**
      * Handles rendering the element on the pdf.
      *
-     * @param stdClass $pdf the pdf object
+     * @param pdf $pdf the pdf object
      */
     public function render($pdf) {
         global $CFG;
@@ -148,7 +147,7 @@ class customcert_elements_image extends customcert_elements_base {
     /**
      * Return the list of possible images to use.
      *
-     * @return array the list of images that can be used.
+     * @return array the list of images that can be used
      */
     public static function get_images() {
         // Create file storage object.

elements/studentname/lib.php

@@ -15,24 +15,23 @@
 // You should have received a copy of the GNU General Public License
 // along with Moodle. If not, see <http://www.gnu.org/licenses/>.
 
+defined('MOODLE_INTERNAL') || die('Direct access to this script is forbidden.');
+
+require_once($CFG->dirroot . '/mod/customcert/elements/element.class.php');
+
 /**
- * The studentname elements core interaction API.
+ * The customcert element studentname's core interaction API.
  *
  * @package    customcertelements_studentname
  * @copyright  Mark Nelson <markn@moodle.com>
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
-
-defined('MOODLE_INTERNAL') || die('Direct access to this script is forbidden.');
-
-require_once($CFG->dirroot . '/mod/customcert/elements/element.class.php');
-
 class customcert_elements_studentname extends customcert_elements_base {
 
     /**
      * Handles rendering the element on the pdf.
      *
-     * @param stdClass $pdf the pdf object
+     * @param pdf $pdf the pdf object
      */
     public function render($pdf) {
         global $USER;

elements/text/lib.php

@@ -15,18 +15,17 @@
 // You should have received a copy of the GNU General Public License
 // along with Moodle. If not, see <http://www.gnu.org/licenses/>.
 
+defined('MOODLE_INTERNAL') || die('Direct access to this script is forbidden.');
+
+require_once($CFG->dirroot . '/mod/customcert/elements/element.class.php');
+
 /**
- * The text elements core interaction API.
+ * The customcert element text's core interaction API.
  *
  * @package    customcertelements_text
  * @copyright  Mark Nelson <markn@moodle.com>
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
-
-defined('MOODLE_INTERNAL') || die('Direct access to this script is forbidden.');
-
-require_once($CFG->dirroot . '/mod/customcert/elements/element.class.php');
-
 class customcert_elements_text extends customcert_elements_base {
 
     /**
@@ -43,7 +42,7 @@ class customcert_elements_text extends customcert_elements_base {
     /**
      * This function renders the form elements when adding a customcert element.
      *
-     * @param stdClass $mform the edit_form instance.
+     * @param mod_customcert_edit_element_form $mform the edit_form instance
      */
     public function render_form_elements($mform) {
         $mform->addElement('textarea', 'text', get_string('text', 'customcertelements_text'));
@@ -57,7 +56,7 @@ class customcert_elements_text extends customcert_elements_base {
      * This will handle how form data will be saved into the data column in the
      * customcert_elements table.
      *
-     * @param stdClass $data the form data.
+     * @param stdClass $data the form data
      * @return string the text
      */
     public function save_unique_data($data) {
@@ -67,7 +66,7 @@ class customcert_elements_text extends customcert_elements_base {
     /**
      * Handles rendering the element on the pdf.
      *
-     * @param stdClass $pdf the pdf object
+     * @param pdf $pdf the pdf object
      */
     public function render($pdf) {
         parent::render_content($pdf, $this->element->data);

lib.php

@@ -55,7 +55,7 @@ define('CUSTOMCERT_MAX_PER_PAGE', 300);
  * Add customcert instance.
  *
  * @param stdClass $data
- * @param stdClass $mform
+ * @param mod_customcert_mod_form $mform
  * @return int new customcert instance id
  */
 function customcert_add_instance($data, $mform) {
@@ -76,7 +76,7 @@ function customcert_add_instance($data, $mform) {
  * Update customcert instance.
  *
  * @param stdClass $data
- * @param stdClass $mform
+ * @param mod_customcert_mod_form $mform
  * @return bool true
  */
 function customcert_update_instance($data, $mform) {
@@ -206,7 +206,7 @@ function customcert_reset_userdata($data) {
  * Implementation of the function for printing the form elements that control
  * whether the course reset functionality affects the customcert.
  *
- * @param $mform form passed by reference
+ * @param mod_customcert_mod_form $mform form passed by reference
  */
 function customcert_reset_course_form_definition(&$mform) {
     $mform->addElement('header', 'customcertheader', get_string('modulenameplural', 'customcert'));

mod_form.php

@@ -33,7 +33,7 @@ class mod_customcert_mod_form extends moodleform_mod {
      * Form definition.
      */
     function definition() {
-        global $CFG, $DB, $OUTPUT;
+        global $CFG;
 
         $mform =& $this->_form;
 
@@ -91,8 +91,8 @@ class mod_customcert_mod_form extends moodleform_mod {
     /**
      * Some basic validation.
      *
-     * @param $data
+     * @param array $data
-     * @param $files
+     * @param array $files
      * @return array the errors that were found
      */
     public function validation($data, $files) {

save_template_form.php

@@ -58,8 +58,8 @@ class mod_customcert_save_template_form extends moodleform {
     /**
      * Some basic validation.
      *
-     * @param $data
+     * @param array $data
-     * @param $files
+     * @param array $files
      * @return array the errors that were found
      */
     public function validation($data, $files) {