Merge branch 'wip-MDL-30985-m23' of git://github.com/samhemelryk/moodle

robjoyce · Mar 1, 2012 · eaf7533 · eaf7533
2 parents 4ab641e + ef6cf87
commit eaf7533
Show file tree

Hide file tree

Showing 11 changed files with 138 additions and 99 deletions.
diff --git a/enrol/category/db/events.php b/enrol/category/db/events.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,12 +15,12 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * category enrolment plugin event handler definition.
+ * Category enrolment plugin event handler definition.
  *
- * @package    enrol
- * @subpackage category
- * @copyright  2010 Petr Skoda {@link http://skodak.org}
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package enrol_category
+ * @category event
+ * @copyright 2010 Petr Skoda {@link http://skodak.org}
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
@@ -42,4 +41,4 @@
         'internal'         => 1,
     ),
 
-);
+);
diff --git a/enrol/cohort/db/events.php b/enrol/cohort/db/events.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,10 +17,10 @@
 /**
  * Cohort enrolment plugin event handler definition.
  *
- * @package    enrol
- * @subpackage cohort
- * @copyright  2010 Petr Skoda {@link http://skodak.org}
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package enrol_cohort
+ * @category event
+ * @copyright 2010 Petr Skoda {@link http://skodak.org}
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();

diff --git a/enrol/meta/db/events.php b/enrol/meta/db/events.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,10 +17,10 @@
 /**
  * Meta course enrolment plugin event handler definition.
  *
- * @package    enrol
- * @subpackage meta
- * @copyright  2010 Petr Skoda {@link http://skodak.org}
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package enrol_meta
+ * @category event
+ * @copyright 2010 Petr Skoda {@link http://skodak.org}
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();

diff --git a/lib/db/events.php b/lib/db/events.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,13 +15,12 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Definition of core event handler
- * and description of all events throws from core.
+ * Definition of core event handler and description of all events throws from core.
  *
- * @package    core
- * @subpackage event
- * @copyright  2007 onwards Martin Dougiamas  http://dougiamas.com
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package core
+ * @category event
+ * @copyright 2007 onwards Martin Dougiamas  http://dougiamas.com
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();

diff --git a/lib/eventslib.php b/lib/eventslib.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
@@ -20,10 +19,9 @@
  *
  * The public API is all at the end of this file.
  *
- * @copyright  1999 onwards Martin Dougiamas  {@link http://moodle.com}
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @package    core
- * @subpackage event
+ * @package core
+ * @copyright 1999 onwards Martin Dougiamas  {@link http://moodle.com}
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
@@ -32,10 +30,10 @@
  * Loads the events definitions for the component (from file). If no
  * events are defined for the component, we simply return an empty array.
  *
- * INTERNAL - to be used from eventslib only
+ * @access protected To be used from eventslib only
  *
  * @param string $component examples: 'moodle', 'mod_forum', 'block_quiz_results'
- * @return array of capabilities or empty array if not exists
+ * @return array Array of capabilities or empty array if not exists
  */
 function events_load_def($component) {
     global $CFG;
@@ -94,7 +92,7 @@ function events_load_def($component) {
  * Gets the capabilities that have been cached in the database for this
  * component.
  *
- * INTERNAL - to be used from eventslib only
+ * @access protected To be used from eventslib only
  *
  * @param string $component examples: 'moodle', 'mod_forum', 'block_quiz_results'
  * @return array of events
@@ -119,13 +117,17 @@ function events_get_cached($component) {
 }
 
 /**
- * We can not removed all event handlers in table, then add them again
- * because event handlers could be referenced by queued items
+ * Updates all of the event definitions within the database.
+ *
+ * Unfortunately this isn't as simple as removing them all and then readding
+ * the updated event definitions. Chances are queued items are referencing the
+ * existing definitions.
  *
  * Note that the absence of the db/events.php event definition file
  * will cause any queued events for the component to be removed from
  * the database.
  *
+ * @category event
  * @param string $component examples: 'moodle', 'mod_forum', 'block_quiz_results'
  * @return boolean always returns true
  */
@@ -194,6 +196,7 @@ function events_update_definition($component='moodle') {
 /**
  * Remove all event handlers and queued events
  *
+ * @category event
  * @param string $component examples: 'moodle', 'mod_forum', 'block_quiz_results'
  */
 function events_uninstall($component) {
@@ -206,7 +209,7 @@ function events_uninstall($component) {
 /**
  * Deletes cached events that are no longer needed by the component.
  *
- * INTERNAL - to be used from eventslib only
+ * @access protected To be used from eventslib only
  *
  * @param string $component examples: 'moodle', 'mod_forum', 'block_quiz_results'
  * @param array $cachedhandlers array of the cached events definitions that will be
@@ -233,14 +236,14 @@ function events_cleanup($component, $cachedhandlers) {
 /****************** End of Events handler Definition code *******************/
 
 /**
- * puts a handler on queue
+ * Puts a handler on queue
  *
- * INTERNAL - to be used from eventslib only
+ * @access protected To be used from eventslib only
  *
- * @param object $handler event handler object from db
- * @param object $event event data object
+ * @param stdClass $handler event handler object from db
+ * @param stdClass $event event data object
  * @param string $errormessage The error message indicating the problem
- * @return id number of new queue handler
+ * @return int id number of new queue handler
  */
 function events_queue_handler($handler, $event, $errormessage) {
     global $DB;
@@ -268,12 +271,12 @@ function events_queue_handler($handler, $event, $errormessage) {
 /**
  * trigger a single event with a specified handler
  *
- * INTERNAL - to be used from eventslib only
+ * @access protected To be used from eventslib only
  *
- * @param handler $hander object from db
- * @param eventdata $eventdata dataobject
+ * @param stdClass $handler This shoudl be a row from the events_handlers table.
+ * @param stdClass $eventdata An object containing information about the event
  * @param string $errormessage error message indicating problem
- * @return bool true means event processed, false means retry event later; may throw exception, NULL means internal error
+ * @return bool|null True means event processed, false means retry event later; may throw exception, NULL means internal error
  */
 function events_dispatch($handler, $eventdata, &$errormessage) {
     global $CFG;
@@ -309,9 +312,9 @@ function events_dispatch($handler, $eventdata, &$errormessage) {
 /**
  * given a queued handler, call the respective event handler to process the event
  *
- * INTERNAL - to be used from eventslib only
+ * @access protected To be used from eventslib only
  *
- * @param object $qhandler events_queued_handler object from db
+ * @param stdClass $qhandler events_queued_handler row from db
  * @return boolean true means event processed, false means retry later, NULL means fatal failure
  */
 function events_process_queued_handler($qhandler) {
@@ -368,9 +371,9 @@ function events_process_queued_handler($qhandler) {
  *
  * Removes events_queue record from events_queue if no more references to this event object exists
  *
- * INTERNAL - to be used from eventslib only
+ * @access protected To be used from eventslib only
  *
- * @param object $qhandler events_queued_handler object from db
+ * @param stdClass $qhandler A row from the events_queued_handler table
  */
 function events_dequeue($qhandler) {
     global $DB;
@@ -387,11 +390,11 @@ function events_dequeue($qhandler) {
 /**
  * Returns handlers for given event. Uses caching for better perf.
  *
- * INTERNAL - to be used from eventslib only
+ * @access protected To be used from eventslib only
  *
  * @staticvar array $handlers
- * @param string $eventanme name of even or 'reset'
- * @return mixed array of handlers or false otherwise
+ * @param string $eventname name of event or 'reset'
+ * @return array|false array of handlers or false otherwise
  */
 function events_get_handlers($eventname) {
     global $DB;
@@ -409,16 +412,13 @@ function events_get_handlers($eventname) {
     return $handlers[$eventname];
 }
 
-/****** Public events API starts here, do not use functions above in 3rd party code ******/
-
-
 /**
  * Events cron will try to empty the events queue by processing all the queued events handlers
  *
- * PUBLIC
- *
+ * @access public Part of the public API
+ * @category event
  * @param string $eventname empty means all
- * @return number of dispatched events
+ * @return int number of dispatched events
  */
 function events_cron($eventname='') {
     global $DB;
@@ -477,10 +477,11 @@ function events_cron($eventname='') {
 /**
  * Function to call all event handlers when triggering an event
  *
- * PUBLIC
- *
+ * @access public Part of the public API.
+ * @category event
  * @param string $eventname name of the event
- * @param object $eventdata event data object
+ * @param string $eventdata event data object. This should contain any data the
+ *     event wants to share and should really be documented by the event publisher
  * @return int number of failed events
  */
 function events_trigger($eventname, $eventdata) {
@@ -586,6 +587,8 @@ function events_trigger($eventname, $eventdata) {
 /**
  * checks if an event is registered for this component
  *
+ * @access public Part of the public API
+ *
  * @param string $eventname name of the event
  * @param string $component component name, can be mod/data or moodle
  * @return bool
@@ -598,7 +601,7 @@ function events_is_registered($eventname, $component) {
 /**
  * checks if an event is queued for processing - either cron handlers attached or failed instant handlers
  *
- * PUBLIC
+ * @access public Part of the public API
  *
  * @param string $eventname name of the event
  * @return int number of queued events
@@ -612,4 +615,4 @@ function events_pending_count($eventname) {
              WHERE h.eventname = ?";
 
     return $DB->count_records_sql($sql, array($eventname));
-}
+}
diff --git a/mod/assignment/db/events.php b/mod/assignment/db/events.php
@@ -1,30 +1,27 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
-///////////////////////////////////////////////////////////////////////////
-// Defines core event handlers                                           //
-///////////////////////////////////////////////////////////////////////////
-//                                                                       //
-// NOTICE OF COPYRIGHT                                                   //
-//                                                                       //
-// Moodle - Modular Object-Oriented Dynamic Learning Environment         //
-//          http://moodle.org                                            //
-//                                                                       //
-// Copyright (C) 1999 onwards  Martin Dougiamas  http://moodle.com       //
-//                                                                       //
-// This program is free software; you can redistribute it and/or modify  //
-// it under the terms of the GNU General Public License as published by  //
-// the Free Software Foundation; either version 3 of the License, or     //
-// (at your option) any later version.                                   //
-//                                                                       //
-// This program is distributed in the hope that it will be useful,       //
-// but WITHOUT ANY WARRANTY; without even the implied warranty of        //
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         //
-// GNU General Public License for more details:                          //
-//                                                                       //
-//          http://www.gnu.org/copyleft/gpl.html                         //
-//                                                                       //
-///////////////////////////////////////////////////////////////////////////
-
+/**
+ * Definition of assignment event handlers
+ *
+ * @package mod_assignment
+ * @category event
+ * @copyright 1999 onwards Martin Dougiamas  http://dougiamas.com
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 
 $handlers = array();
 

diff --git a/mod/chat/db/events.php b/mod/chat/db/events.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,9 +17,10 @@
 /**
  * User logout event handler definition.
  *
- * @package   mod_chat
+ * @package mod_chat
+ * @category event
  * @copyright 2010 Dongsheng Cai <[email protected]>
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 /* List of handlers */