From a26f0c2c6648fcf094e6c5775f4431c59cb207c4 Mon Sep 17 00:00:00 2001 From: Mark Nelson Date: Wed, 12 Jun 2013 18:35:27 +0800 Subject: [PATCH] Tidied up the PHPDocs and set the base element to an abstract class --- edit_element_form.php | 6 +++--- elements/code/lib.php | 13 ++++++------- elements/date/lib.php | 21 ++++++++++----------- elements/element.class.php | 23 ++++++++++++++--------- elements/grade/lib.php | 19 +++++++++---------- elements/image/lib.php | 19 +++++++++---------- elements/studentname/lib.php | 13 ++++++------- elements/text/lib.php | 17 ++++++++--------- lib.php | 6 +++--- mod_form.php | 6 +++--- save_template_form.php | 4 ++-- 11 files changed, 73 insertions(+), 74 deletions(-) diff --git a/edit_element_form.php b/edit_element_form.php index b489296..6b7902b 100644 --- a/edit_element_form.php +++ b/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 $files + * @param array $data + * @param array $files * @return array the errors that were found */ public function validation($data, $files) { diff --git a/elements/code/lib.php b/elements/code/lib.php index 3f21dfb..87286b4 100644 --- a/elements/code/lib.php +++ b/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 . +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 * @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; diff --git a/elements/date/lib.php b/elements/date/lib.php index 9fc5c26..20bd145 100644 --- a/elements/date/lib.php +++ b/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 . -/** - * The date elements core interaction API. - * - * @package customcertelements_date - * @copyright Mark Nelson - * @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 + * @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. diff --git a/elements/element.class.php b/elements/element.class.php index 6a67689..11cdb9c 100644 --- a/elements/element.class.php +++ b/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. diff --git a/elements/grade/lib.php b/elements/grade/lib.php index 1e0520d..3f7d84e 100644 --- a/elements/grade/lib.php +++ b/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 . -/** - * The grade elements core interaction API. - * - * @package customcertelements_grade - * @copyright Mark Nelson - * @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 + * @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; diff --git a/elements/image/lib.php b/elements/image/lib.php index 8051761..33df5b6 100644 --- a/elements/image/lib.php +++ b/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 . +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 * @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. diff --git a/elements/studentname/lib.php b/elements/studentname/lib.php index e65ae1f..af7a3a6 100644 --- a/elements/studentname/lib.php +++ b/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 . +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 * @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; diff --git a/elements/text/lib.php b/elements/text/lib.php index 5113171..66d0b1a 100644 --- a/elements/text/lib.php +++ b/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 . +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 * @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); diff --git a/lib.php b/lib.php index d64dc21..4f523b1 100644 --- a/lib.php +++ b/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')); diff --git a/mod_form.php b/mod_form.php index dc2acae..0c0113d 100644 --- a/mod_form.php +++ b/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 $files + * @param array $data + * @param array $files * @return array the errors that were found */ public function validation($data, $files) { diff --git a/save_template_form.php b/save_template_form.php index 41b2bb7..581af28 100644 --- a/save_template_form.php +++ b/save_template_form.php @@ -58,8 +58,8 @@ class mod_customcert_save_template_form extends moodleform { /** * Some basic validation. * - * @param $data - * @param $files + * @param array $data + * @param array $files * @return array the errors that were found */ public function validation($data, $files) {