From 1d1719f5dde75cb11b26ddc4566e65aa75cac543 Mon Sep 17 00:00:00 2001
From: Sam Hemelryk <sam@moodle.com>
Date: Tue, 17 Jan 2012 13:50:58 +0800
Subject: [PATCH] MDL-30985 Fixed up event API phpdocs

---
 enrol/category/db/events.php       | 13 +++----
 enrol/cohort/db/events.php         |  9 ++---
 enrol/meta/db/events.php           |  9 ++---
 lib/db/events.php                  |  9 ++---
 lib/eventslib.php                  | 61 ++++++++++++++++--------------
 mod/assignment/db/events.php       | 47 +++++++++++------------
 mod/chat/db/events.php             |  6 +--
 mod/forum/db/events.php            |  6 +--
 mod/quiz/db/events.php             |  6 +--
 portfolio/googledocs/db/events.php | 23 +++++++++++
 portfolio/picasa/db/events.php     | 27 +++++++++++--
 11 files changed, 129 insertions(+), 87 deletions(-)

diff --git a/enrol/category/db/events.php b/enrol/category/db/events.php
index 37b2d64c9ce..66194df447d 100644
--- 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 @@ $handlers = array (
         'internal'         => 1,
     ),
 
-);
+);
\ No newline at end of file
diff --git a/enrol/cohort/db/events.php b/enrol/cohort/db/events.php
index 4a596aa15c7..4f26a20be4e 100644
--- 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
index 6e4152e27e4..c1a2d70ecdd 100644
--- 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
index e6c52d53558..ecc8c46d4fd 100644
--- 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
@@ -19,10 +18,10 @@
  * 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_event
+ * @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
index 6ceaf5e0059..bbf9cbea7d6 100644
--- 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_event
+ * @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,7 +30,7 @@ defined('MOODLE_INTERNAL') || die();
  * 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 INTERNAL - 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
@@ -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 INTERNAL - to be used from eventslib only
  *
  * @param string $component examples: 'moodle', 'mod_forum', 'block_quiz_results'
  * @return array of events
@@ -126,6 +124,8 @@ function events_get_cached($component) {
  * 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 +194,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 +207,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 INTERNAL - 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 +234,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 INTERNAL - 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 +269,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 INTERNAL - to be used from eventslib only
  *
- * @param handler $hander object from db
- * @param eventdata $eventdata dataobject
+ * @param stdClass $hander Row from db
+ * @param stdClass $eventdata dataobject
  * @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 +310,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 INTERNAL - 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 +369,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 INTERNAL - to be used from eventslib only
  *
- * @param object $qhandler events_queued_handler object from db
+ * @param stdClass $qhandler events_queued_handler row from db
  */
 function events_dequeue($qhandler) {
     global $DB;
@@ -387,11 +388,11 @@ function events_dequeue($qhandler) {
 /**
  * Returns handlers for given event. Uses caching for better perf.
  *
- * INTERNAL - to be used from eventslib only
+ * @access protected INTERNAL - 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
+ * @return array|false array of handlers or false otherwise
  */
 function events_get_handlers($eventname) {
     global $DB;
@@ -415,10 +416,11 @@ function events_get_handlers($eventname) {
 /**
  * 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,7 +479,8 @@ 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
@@ -586,6 +589,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 +603,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 +617,4 @@ function events_pending_count($eventname) {
              WHERE h.eventname = ?";
 
     return $DB->count_records_sql($sql, array($eventname));
-}
+}
\ No newline at end of file
diff --git a/mod/assignment/db/events.php b/mod/assignment/db/events.php
index 7234b30e430..265538273df 100644
--- 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
index 9203d970273..a33062fff22 100644
--- 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 <dongsheng@moodle.com>
- * @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 */
diff --git a/mod/forum/db/events.php b/mod/forum/db/events.php
index a6138e13b13..064483e6775 100644
--- a/mod/forum/db/events.php
+++ b/mod/forum/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 @@
 /**
  * Meta course enrolment plugin event handler definition.
  *
- * @package   enrol_meta
+ * @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
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 /* List of handlers */
diff --git a/mod/quiz/db/events.php b/mod/quiz/db/events.php
index bfb7b5c3527..0a9de7edcee 100644
--- a/mod/quiz/db/events.php
+++ b/mod/quiz/db/events.php
@@ -15,10 +15,10 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Post-install code for the quiz module.
+ * Add event handlers for the quiz
  *
- * @package    mod
- * @subpackage quiz
+ * @package    mod_quiz
+ * @category   event
  * @copyright  2011 The Open University
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
diff --git a/portfolio/googledocs/db/events.php b/portfolio/googledocs/db/events.php
index 98b9dbd340c..b0d3d0c702f 100644
--- a/portfolio/googledocs/db/events.php
+++ b/portfolio/googledocs/db/events.php
@@ -1,4 +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/>.
+
+/**
+ * Add event handlers for the googledocs portfolio.
+ *
+ * @package    portfolio_googledocs
+ * @category   event
+ * @copyright  2009 Penny Leach
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 
 $handlers = array (
     'user_deleted' => array (
diff --git a/portfolio/picasa/db/events.php b/portfolio/picasa/db/events.php
index afca2ebd0ef..09ef7cca20c 100644
--- a/portfolio/picasa/db/events.php
+++ b/portfolio/picasa/db/events.php
@@ -1,4 +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/>.
+
+/**
+ * Add event handlers for the picasa portfolio.
+ *
+ * @package    portfolio_picasa
+ * @category   event
+ * @copyright  2009 Penny Leach
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 
 $handlers = array (
     'user_deleted' => array (
@@ -7,6 +30,4 @@ $handlers = array (
          'schedule'         => 'cron',
          'internal'         => 0,
      ),
-);
-
-
+);
\ No newline at end of file
-- 
2.17.1