MDL-30987 message: updated phpdocs for /lib/messagelib.php and /message
authorAndrew Davis <andrew@moodle.com>
Thu, 5 Jan 2012 05:05:02 +0000 (12:05 +0700)
committerAndrew Davis <andrew@moodle.com>
Tue, 21 Feb 2012 03:57:55 +0000 (10:57 +0700)
30 files changed:
lib/messagelib.php
message/defaultoutputs.php
message/discussion.php
message/edit.php
message/externallib.php
message/index.php
message/lib.php
message/output/email/db/install.php
message/output/email/db/upgrade.php
message/output/email/lang/en/message_email.php
message/output/email/lib.php
message/output/email/message_output_email.php
message/output/email/settings.php
message/output/email/version.php
message/output/jabber/db/install.php
message/output/jabber/db/upgrade.php
message/output/jabber/lang/en/message_jabber.php
message/output/jabber/lib.php
message/output/jabber/message_output_jabber.php
message/output/jabber/settings.php
message/output/jabber/version.php
message/output/lib.php
message/output/popup/db/install.php
message/output/popup/db/upgrade.php
message/output/popup/lang/en/message_popup.php
message/output/popup/lib.php
message/output/popup/message_output_popup.php
message/output/popup/version.php
message/renderer.php
message/send_form.php

index bbbfccf..4c5b564 100644 (file)
@@ -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
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * messagelib.php - Contains generic messaging functions for the message system
+ * Functions for interacting with the message system
  *
- * @package    core
- * @subpackage message
- * @copyright  Luis Rodrigues and Martin Dougiamas
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package   core_message
+ * @copyright 2008 Luis Rodrigues and Martin Dougiamas
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
@@ -30,8 +28,8 @@ require_once(dirname(dirname(__FILE__)) . '/message/lib.php');
 
 /**
  * Called when a message provider wants to send a message.
- * This functions checks the user's processor configuration to send the given type of message,
- * then tries to send it.
+ * This functions checks the message recipient's message processor configuration then 
+ * sends the message to the configured processors
  *
  * Required parameter $eventdata structure:
  *  component string component name. must exist in message_providers
@@ -46,8 +44,9 @@ require_once(dirname(dirname(__FILE__)) . '/message/lib.php');
  *  contexturl - if this is a notification then you can specify a url to view the event. For example the forum post the user is being notified of.
  *  contexturlname - the display text for contexturl
  *
+ * @category message
  * @param object $eventdata information about the message (component, userfrom, userto, ...)
- * @return int|false the ID of the new message or false if there was a problem with a processor
+ * @return mixed the integer ID of the new message or false if there was a problem with a processor
  */
 function message_send($eventdata) {
     global $CFG, $DB;
@@ -205,10 +204,10 @@ function message_send($eventdata) {
 
 
 /**
- * This code updates the message_providers table with the current set of providers
+ * Updates the message_providers table with the current set of message providers
  *
- * @param $component - examples: 'moodle', 'mod_forum', 'block_quiz_results'
- * @return boolean
+ * @param string $component For example 'moodle', 'mod_forum' or 'block_quiz_results'
+ * @return boolean True on success
  */
 function message_update_providers($component='moodle') {
     global $DB;
@@ -265,8 +264,7 @@ function message_update_providers($component='moodle') {
  * when the new message processor is added.
  *
  * @param string $processorname The name of message processor plugin (e.g. 'email', 'jabber')
- * @return void
- * @throws invalid_parameter_exception if $processorname does not exist
+ * @throws invalid_parameter_exception if $processorname does not exist in the database
  */
 function message_update_processors($processorname) {
     global $DB;
@@ -291,13 +289,12 @@ function message_update_processors($processorname) {
 }
 
 /**
- * Setting default messaging preference for particular message provider
+ * Setting default messaging preferences for particular message provider
  *
  * @param  string $component   The name of component (e.g. moodle, mod_forum, etc.)
  * @param  string $messagename The name of message provider
  * @param  array  $fileprovider The value of $messagename key in the array defined in plugin messages.php
- * @param  string $processorname The optinal name of message processor
- * @return void
+ * @param  string $processorname The optional name of message processor
  */
 function message_set_default_message_preference($component, $messagename, $fileprovider, $processorname='') {
     global $DB;
@@ -364,13 +361,14 @@ function message_set_default_message_preference($component, $messagename, $filep
 }
 
 /**
- * Returns the active providers for the current user, based on capability
+ * This function has been deprecated please use message_get_providers_for_user() instead.
  *
- * This function has been deprecated please use {@see message_get_providers_for_user()} instead.
+ * Returns the active providers for the current user, based on capability
  *
+ * @see message_get_providers_for_user()}
  * @deprecated since 2.1
- * @todo Remove in 2.2
- * @return array of message providers
+ * @todo Remove in 2.2 (MDL-31031)
+ * @return array An array of message providers
  */
 function message_get_my_providers() {
     global $USER;
@@ -381,7 +379,7 @@ function message_get_my_providers() {
  * Returns the active providers for the user specified, based on capability
  *
  * @param int $userid id of user
- * @return array of message providers
+ * @return array An array of message providers
  */
 function message_get_providers_for_user($userid) {
     global $DB, $CFG;
@@ -409,10 +407,11 @@ function message_get_providers_for_user($userid) {
 /**
  * Gets the message providers that are in the database for this component.
  *
- * @param $component - examples: 'moodle', 'mod/forum', 'block/quiz_results'
- * @return array of message providers
+ * This is an internal function used within messagelib.php
  *
- * INTERNAL - to be used from messagelib only
+ * @see message_update_providers()}
+ * @param string $component A moodle component like 'moodle', 'mod_forum', 'block_quiz_results'
+ * @return array An array of message providers
  */
 function message_get_providers_from_db($component) {
     global $DB;
@@ -421,13 +420,15 @@ function message_get_providers_from_db($component) {
 }
 
 /**
- * Loads the messages definitions for the component (from file). If no
- * messages are defined for the component, we simply return an empty array.
+ * Loads the messages definitions for a component from file
  *
- * @param $component - examples: 'moodle', 'mod_forum', 'block_quiz_results'
- * @return array of message providerss or empty array if not exists
+ * If no messages are defined for the component, return an empty array.
+ * This is an internal function used within messagelib.php
  *
- * INTERNAL - to be used from messagelib only
+ * @see message_update_providers()
+ * @see message_update_processors()
+ * @param string $component A moodle component like 'moodle', 'mod_forum', 'block_quiz_results'
+ * @return array An array of message providers or empty array if not exists
  */
 function message_get_providers_from_file($component) {
     $defpath = get_component_directory($component).'/db/messages.php';
@@ -451,9 +452,9 @@ function message_get_providers_from_file($component) {
 }
 
 /**
- * Remove all message providers for particular plugin and corresponding settings
+ * Remove all message providers for particular component and corresponding settings
  *
- * @param string $component - examples: 'moodle', 'mod_forum', 'block_quiz_results'
+ * @param string $component A moodle component like 'moodle', 'mod_forum', 'block_quiz_results'
  * @return void
  */
 function message_provider_uninstall($component) {
@@ -467,10 +468,9 @@ function message_provider_uninstall($component) {
 }
 
 /**
- * Remove message processor
+ * Uninstall a message processor
  *
- * @param string $name - examples: 'email', 'jabber'
- * @return void
+ * @param string $name A message processor name like 'email', 'jabber'
  */
 function message_processor_uninstall($name) {
     global $DB;
index 4331ab5..4d94cc4 100644 (file)
@@ -17,9 +17,9 @@
 /**
  * Default message outputs configuration page
  *
- * @package    message
- * @copyright  2011 Lancaster University Network Services Limited
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package   core_message
+ * @copyright 2011 Lancaster University Network Services Limited
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 require_once(dirname(__FILE__) . '/../config.php');
 require_once($CFG->dirroot . '/message/lib.php');
@@ -112,4 +112,4 @@ $messageoutputs = $renderer->manage_defaultmessageoutputs($processors, $provider
 echo $OUTPUT->header();
 echo $OUTPUT->heading(get_string('defaultmessageoutputs', 'message'));
 echo $messageoutputs;
-echo $OUTPUT->footer();
\ No newline at end of file
+echo $OUTPUT->footer();
index a588e5e..0717ea4 100644 (file)
@@ -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
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * This file was replaced by index.php in Moodle 2.0
- * It now simply redirects to index.php
+ * This file was replaced by index.php in Moodle 2.0 and now simply redirects to index.php
  *
- * @author Luis Rodrigues and Martin Dougiamas
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @package message
+ * @package    core_message
+ * @copyright  2005 Luis Rodrigues and Martin Dougiamas
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
     require(dirname(dirname(__FILE__)) . '/config.php');
index 17e0e75..9cabdc2 100644 (file)
@@ -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,9 @@
 /**
  * Edit user message preferences
  *
- * @author Luis Rodrigues and Martin Dougiamas
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @package message
+ * @package    core_message
+ * @copyright  2008 Luis Rodrigues and Martin Dougiamas
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 require_once(dirname(__FILE__) . '/../config.php');
index 3e5a03a..bad48b6 100644 (file)
@@ -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 @@
 /**
  * External message API
  *
- * @package    moodlecore
- * @subpackage message
+ * @package    core_message
  * @copyright  2011 Moodle Pty Ltd (http://moodle.com)
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -27,6 +25,10 @@ require_once("$CFG->libdir/externallib.php");
 
 /**
  * Message functions
+ *
+ * @package    core_message
+ * @copyright  2011 Moodle Pty Ltd (http://moodle.com)
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later  (6)
  */
 class core_message_external extends external_api {
 
@@ -53,7 +55,7 @@ class core_message_external extends external_api {
     /**
      * Send private messages from the current USER to other users
      *
-     * @param $messages  An array of message to send.
+     * @param array $messages An array of message to send
      * @return boolean
      */
     public static function send_instant_messages($messages = array()) {
@@ -173,12 +175,16 @@ class core_message_external extends external_api {
 
 /**
  * Deprecated message functions
+ *
  * @deprecated since Moodle 2.2 please use core_message_external instead
+ * @copyright 2011 Moodle Pty Ltd (http://moodle.com)
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class moodle_message_external extends external_api {
 
     /**
      * Returns description of method parameters
+     *
      * @deprecated since Moodle 2.2 please use core_message_external::send_instant_messages_parameters instead
      * @return external_function_parameters
      */
@@ -188,8 +194,9 @@ class moodle_message_external extends external_api {
 
     /**
      * Send private messages from the current USER to other users
+     *
      * @deprecated since Moodle 2.2 please use core_message_external::send_instant_messages instead
-     * @param $messages  An array of message to send.
+     * @param array $messages  An array of message to send.
      * @return boolean
      */
     public static function send_instantmessages($messages = array()) {
@@ -198,6 +205,7 @@ class moodle_message_external extends external_api {
 
     /**
      * Returns description of method result value
+     *
      * @deprecated since Moodle 2.2 please use core_message_external::send_instant_messages_returns instead
      * @return external_description
      */
@@ -205,4 +213,4 @@ class moodle_message_external extends external_api {
         return core_message_external::send_instant_messages_returns();
     }
 
-}
\ No newline at end of file
+}
index 6910282..e21b99f 100644 (file)
@@ -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,9 @@
 /**
  * A page displaying the user's contacts and messages
  *
- * @package   moodlecore
- * @copyright 2010 Andrew Davis
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package    core_message
+ * @copyright  2010 Andrew Davis
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 require_once('../config.php');
index 023b994..1024efd 100644 (file)
@@ -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,9 @@
 /**
  * Library functions for messaging
  *
- * @copyright Luis Rodrigues
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @package message
+ * @package   core_message
+ * @copyright 2008 Luis Rodrigues
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 require_once($CFG->libdir.'/eventslib.php');
@@ -799,9 +798,8 @@ function message_get_recent_notifications($user, $limitfrom=0, $limitto=100) {
 /**
  * Print the user's recent conversations
  *
- * @param object $user1 the current user
+ * @param stdClass $user the current user
  * @param bool $showicontext flag indicating whether or not to show text next to the action icons
- * @return void
  */
 function message_print_recent_conversations($user=null, $showicontext=false) {
     global $USER;
@@ -823,8 +821,7 @@ function message_print_recent_conversations($user=null, $showicontext=false) {
 /**
  * Print the user's recent notifications
  *
- * @param object $user1 the current user
- * @return void
+ * @param stdClass $user the current user
  */
 function message_print_recent_notifications($user=null) {
     global $USER;
@@ -847,7 +844,6 @@ function message_print_recent_notifications($user=null) {
 /**
  * Print a list of recent messages
  *
- * @staticvar type $dateformat
  * @param array $messages the messages to display
  * @param object $user the current user
  * @param bool $showotheruser display information on the other user?
@@ -959,7 +955,7 @@ function message_add_contact($contactid, $blocked=0) {
 /**
  * remove a contact
  *
- * @param type $contactid the user ID of the contact to remove
+ * @param int $contactid the user ID of the contact to remove
  * @return bool returns the result of delete_records()
  */
 function message_remove_contact($contactid) {
@@ -1323,7 +1319,6 @@ function message_print_user ($user=false, $iscontact=false, $isblocked=false, $i
 /**
  * Print a message contact link
  *
- * @staticvar type $str
  * @param int $userid the ID of the user to apply to action to
  * @param string $linktype can be add, remove, block or unblock
  * @param bool $return if true return the link as a string. If false echo the link.
@@ -1399,7 +1394,6 @@ function message_contact_link($userid, $linktype='add', $return=false, $script=n
 /**
  * echo or return a link to take the user to the full message history between themselves and another user
  *
- * @staticvar type $strmessagehistory
  * @param int $userid1 the ID of the user displayed on the left (usually the current user)
  * @param int $userid2 the ID of the other user
  * @param bool $return true to return the link as a string. False to echo the link.
@@ -2048,7 +2042,7 @@ function message_post_message($userfrom, $userto, $message, $format) {
  * This was the simple way to code the SQL ... is it going to blow up
  * on large datasets?
  *
- * @todo: deprecated - to be deleted in 2.2
+ * @deprecated To be deleted in 2.2 MDL-31709
  * @return array
  */
 function message_get_participants() {
@@ -2135,7 +2129,7 @@ function message_print_contactlist_user($contact, $incontactlist = true, $isbloc
  *
  * @param bool $incontactlist is the user a contact
  * @param bool $isblocked is the user blocked
- * @param type $contact contact object
+ * @param stdClass $contact contact object
  * @param string $script the URL to send the user to when the link is clicked. If null, the current page.
  * @param bool $text include text next to the icons?
  * @param bool $icon include a graphical icon?
@@ -2158,9 +2152,9 @@ function message_get_contact_add_remove_link($incontactlist, $isblocked, $contac
 /**
  * Constructs the block contact link to display next to other users
  *
- * @param bool $incontactlist is the user a contact
- * @param bool $isblocked is the user blocked
- * @param type $contact contact object
+ * @param bool $incontactlist is the user a contact?
+ * @param bool $isblocked is the user blocked?
+ * @param stdClass $contact contact object
  * @param string $script the URL to send the user to when the link is clicked. If null, the current page.
  * @param bool $text include text next to the icons?
  * @param bool $icon include a graphical icon?
@@ -2224,7 +2218,7 @@ function message_mark_messages_read($touserid, $fromuserid){
 /**
  * Mark a single message as read
  *
- * @param message an object with an object property ie $message->id which is an id in the message table
+ * @param stdClass $message An object with an object property ie $message->id which is an id in the message table
  * @param int $timeread the timestamp for when the message should be marked read. Usually time().
  * @param bool $messageworkingempty Is the message_working table already confirmed empty for this message?
  * @return int the ID of the message in the message_read table
index eaa59f5..a7f26db 100644 (file)
@@ -1,5 +1,30 @@
 <?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/>.
 
+/**
+ * Installation code for the email message processor
+ *
+ * @package    message_email
+ * @copyright  2009 Moodle Pty Ltd (http://moodle.com)
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Install the email message processor
+ */
 function xmldb_message_email_install() {
     global $DB;
     $result = true;
index 14d7a8a..dd79b5c 100644 (file)
@@ -1,36 +1,32 @@
 <?php
-
-///////////////////////////////////////////////////////////////////////////
-//                                                                       //
-// NOTICE OF COPYRIGHT                                                   //
-//                                                                       //
-// Moodle - Modular Object-Oriented Dynamic Learning Environment         //
-//          http://moodle.com                                            //
-//                                                                       //
-// 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 2 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                         //
-//                                                                       //
-///////////////////////////////////////////////////////////////////////////
+// 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/>.
 
 /**
  * Upgrade code for email message processor
  *
- * @author Luis Rodrigues
- * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
- * @package
+ * @package    message_email
+ * @copyright  2008 Luis Rodrigues
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU Public License
  */
 
+/**
+ * Upgrade code for the email message processor
+ *
+ * @param int $oldversion The version that we are upgrading from
+ */
 function xmldb_message_email_upgrade($oldversion) {
     global $CFG, $DB;
 
index ae06d11..611eca1 100644 (file)
@@ -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
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Strings for component 'message_email', language 'en', branch 'MOODLE_20_STABLE'
+ * Strings for component 'message_email', language 'en'
  *
- * @package   message_email
- * @copyright 1999 onwards Martin Dougiamas  {@link http://moodle.com}
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package    message_email
+ * @copyright  1999 onwards Martin Dougiamas  {@link http://moodle.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 $string['allowusermailcharset'] = 'Allow user to select character set';
index 7b5d130..26d0754 100644 (file)
@@ -1,38 +1,29 @@
 <?php
-
-///////////////////////////////////////////////////////////////////////////
-//                                                                       //
-// NOTICE OF COPYRIGHT                                                   //
-//                                                                       //
-// Moodle - Modular Object-Oriented Dynamic Learning Environment         //
-//          http://moodle.com                                            //
-//                                                                       //
-// 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 2 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                         //
-//                                                                       //
-///////////////////////////////////////////////////////////////////////////
+// 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/>.
 
 /**
- * Email message processor - lib file
+ * Email message processor library file
  *
- * @author Luis Rodrigues
- * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
- * @package
+ * @package    message_email
+ * @copyright  2008 Luis Rodrigues and Martin Dougiamas
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 /**
- * Register the processor.
+ * Register the processor
  */
 function email_install(){
     global $DB;
index 80262db..a300b09 100644 (file)
@@ -1,37 +1,36 @@
 <?php
-
-///////////////////////////////////////////////////////////////////////////
-//                                                                       //
-// NOTICE OF COPYRIGHT                                                   //
-//                                                                       //
-// Moodle - Modular Object-Oriented Dynamic Learning Environment         //
-//          http://moodle.com                                            //
-//                                                                       //
-// 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 2 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                         //
-//                                                                       //
-///////////////////////////////////////////////////////////////////////////
+// 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/>.
 
 /**
- * Email message processor - send a given message by email
+ * Contains the definiton of the email message processors (sends messages to users via email)
  *
- * @author Luis Rodrigues
- * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
- * @package
+ * @package   message_email
+ * @copyright 2008 Luis Rodrigues and Martin Dougiamas
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
+
 require_once($CFG->dirroot.'/message/output/lib.php');
 
+/**
+ * The email message processor
+ *
+ * @package   message_email
+ * @copyright 2008 Luis Rodrigues and Martin Dougiamas
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class message_output_email extends message_output {
     /**
      * Processes the message (sends by email).
@@ -71,7 +70,8 @@ class message_output_email extends message_output {
 
     /**
      * Creates necessary fields in the messaging config form.
-     * @param object $mform preferences form class
+     *
+     * @param array $preferences An array of user preferences
      */
     function config_form($preferences){
         global $USER, $OUTPUT;
@@ -91,8 +91,9 @@ class message_output_email extends message_output {
     }
 
     /**
-     * Parses the form submitted data and saves it into preferences array.
-     * @param object $mform preferences form class
+     * Parses the submitted form data and saves it into preferences array.
+     *
+     * @param stdClass $form preferences form class
      * @param array $preferences preferences array
      */
     function process_form($form, &$preferences){
@@ -102,16 +103,17 @@ class message_output_email extends message_output {
     }
 
     /**
-     * @return int the Default message output settings for this output, for
-     * message providers that do not specify what the settings should be for
-     * this output in the messages.php file.
+     * Returns the default message output settings for this output
+     *
+     * @return int The default settings
      */
     public function get_default_messaging_settings() {
         return MESSAGE_PERMITTED + MESSAGE_DEFAULT_LOGGEDIN + MESSAGE_DEFAULT_LOGGEDOFF;
     }
 
     /**
-     * Loads the config data from database to put on the form (initial load)
+     * Loads the config data from database to put on the form during initial form display
+     *
      * @param array $preferences preferences array
      * @param int $userid the user id
      */
index 7b7e723..240a9fb 100644 (file)
 /**
  * Email configuration page
  *
- * @package    message
- * @subpackage email
- * @copyright  2011 Lancaster University Network Services Limited
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package   message_email
+ * @copyright 2011 Lancaster University Network Services Limited
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die;
@@ -41,4 +40,4 @@ if ($ADMIN->fulltree) {
     $settings->add(new admin_setting_configcheckbox('allowusermailcharset', get_string('allowusermailcharset', 'message_email'), get_string('configallowusermailcharset', 'message_email'), 0));
     $options = array('LF'=>'LF', 'CRLF'=>'CRLF');
     $settings->add(new admin_setting_configselect('mailnewline', get_string('mailnewline', 'message_email'), get_string('configmailnewline','message_email'), 'LF', $options));
-}
\ No newline at end of file
+}
index 55229bb..0d8a892 100644 (file)
@@ -17,9 +17,8 @@
 /**
  * Email processor version information
  *
- * @package    message
- * @subpackage email
- * @author     Luis Rodrigues
+ * @package    message_email
+ * @copyright  2008 Luis Rodrigues
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
index 2496094..3ecd680 100644 (file)
@@ -1,4 +1,30 @@
 <?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/>.
+
+/**
+ * Jabber message processor installation code
+ *
+ * @package    message_jabber
+ * @copyright  2009 Dongsheng Cai <dongsheng@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Install the Jabber message processor
+ */
 function xmldb_message_jabber_install(){
     global $DB;
 
index 48e12b3..d884f25 100644 (file)
@@ -1,36 +1,32 @@
 <?php
-
-///////////////////////////////////////////////////////////////////////////
-//                                                                       //
-// NOTICE OF COPYRIGHT                                                   //
-//                                                                       //
-// Moodle - Modular Object-Oriented Dynamic Learning Environment         //
-//          http://moodle.com                                            //
-//                                                                       //
-// 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 2 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                         //
-//                                                                       //
-///////////////////////////////////////////////////////////////////////////
+// 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/>.
 
 /**
  * Upgrade code for jabber message processor
  *
- * @author Luis Rodrigues
- * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
- * @package
+ * @package   message_jabber
+ * @copyright 2008 Luis Rodrigues
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
+/**
+ * Upgrade code for the jabber message processor
+ *
+ * @param int $oldversion The version that we are upgrading from
+ */
 function xmldb_message_jabber_upgrade($oldversion) {
     global $CFG, $DB;
 
index e38f699..e00b6ee 100644 (file)
@@ -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
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Strings for component 'message_jabber', language 'en', branch 'MOODLE_20_STABLE'
+ * Strings for component 'message_jabber', language 'en'
  *
- * @package   message_jabber
- * @copyright 1999 onwards Martin Dougiamas  {@link http://moodle.com}
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package    message_jabber
+ * @copyright  1999 onwards Martin Dougiamas  {@link http://moodle.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 $string['configjabberhost'] = 'The server to connect to to send jabber message notifications';
index b5ed258..c0e677f 100644 (file)
@@ -1,34 +1,25 @@
 <?php
-
-///////////////////////////////////////////////////////////////////////////
-//                                                                       //
-// NOTICE OF COPYRIGHT                                                   //
-//                                                                       //
-// Moodle - Modular Object-Oriented Dynamic Learning Environment         //
-//          http://moodle.com                                            //
-//                                                                       //
-// 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 2 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                         //
-//                                                                       //
-///////////////////////////////////////////////////////////////////////////
+// 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/>.
 
 /**
  * Jabber message processor - lib file
  *
- * @author Luis Rodrigues
- * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
- * @package
+ * @package    message_jabber
+ * @copyright  2008 Luis Rodrigues
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU Public License
  */
 
 /**
index c4dbbba..c4c9974 100644 (file)
@@ -1,44 +1,43 @@
 <?php
-
-///////////////////////////////////////////////////////////////////////////
-//                                                                       //
-// NOTICE OF COPYRIGHT                                                   //
-//                                                                       //
-// Moodle - Modular Object-Oriented Dynamic Learning Environment         //
-//          http://moodle.com                                            //
-//                                                                       //
-// 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 2 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                         //
-//                                                                       //
-///////////////////////////////////////////////////////////////////////////
+// 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/>.
 
 /**
- * Jabber message processor - send a given message by jabber
+ * Jabber message processor to send messages by jabber
  *
- * @author Luis Rodrigues
- * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
- * @package
+ * @package    message_jabber
+ * @copyright  2008 Luis Rodrigues
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU Public License
  */
 
 require_once($CFG->dirroot.'/message/output/lib.php');
 require_once($CFG->libdir.'/jabber/XMPP/XMPP.php');
 
+/**
+ * The jabber message processor
+ *
+ * @package   message_jabber
+ * @copyright 2008 Luis Rodrigues
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class message_output_jabber extends message_output {
 
     /**
-     * Processes the message (sends using jabber).
-     * @param object $eventdata the event data submitted by the message sender plus $eventdata->savedmessageid
+     * Processes the message and sends a notification via jabber
+     *
+     * @param stdClass $eventdata the event data submitted by the message sender plus $eventdata->savedmessageid
      * @return true if ok, false if error
      */
     function send_message($eventdata){
@@ -90,7 +89,8 @@ class message_output_jabber extends message_output {
 
     /**
      * Creates necessary fields in the messaging config form.
-     * @param object $mform preferences form class
+     *
+     * @param array $preferences An array of user preferences
      */
     function config_form($preferences){
         global $CFG;
@@ -103,8 +103,9 @@ class message_output_jabber extends message_output {
     }
 
     /**
-     * Parses the form submitted data and saves it into preferences array.
-     * @param object $mform preferences form class
+     * Parses the submitted form data and saves it into preferences array.
+     *
+     * @param stdClass $form preferences form class
      * @param array $preferences preferences array
      */
     function process_form($form, &$preferences){
@@ -114,7 +115,8 @@ class message_output_jabber extends message_output {
     }
 
     /**
-     * Loads the config data from database to put on the form (initial load)
+     * Loads the config data from database to put on the form during initial form display
+     *
      * @param array $preferences preferences array
      * @param int $userid the user id
      */
index 3f7428f..85c833f 100644 (file)
@@ -17,8 +17,7 @@
 /**
  * Jabber configuration page
  *
- * @package    message
- * @subpackage jabber
+ * @package    message_jabber
  * @copyright  2011 Lancaster University Network Services Limited
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -31,4 +30,4 @@ if ($ADMIN->fulltree) {
     $settings->add(new admin_setting_configtext('jabberusername', get_string('jabberusername', 'message_jabber'), get_string('configjabberusername', 'message_jabber'), '', PARAM_RAW));
     $settings->add(new admin_setting_configpasswordunmask('jabberpassword', get_string('jabberpassword', 'message_jabber'), get_string('configjabberpassword', 'message_jabber'), ''));
     $settings->add(new admin_setting_configtext('jabberport', get_string('jabberport', 'message_jabber'), get_string('configjabberport', 'message_jabber'), 5222, PARAM_INT));
-}
\ No newline at end of file
+}
index 7ecc5bb..f0a009d 100644 (file)
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Jabber processor version information
+ * Jabber message processor version information
  *
- * @package    message
- * @subpackage jabber
- * @author     Luis Rodrigues
+ * @package    message_jabber
+ * @copyright  2008 Luis Rodrigues
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
index 7d7aa3a..1860fc5 100644 (file)
@@ -1,64 +1,93 @@
 <?php
-
-///////////////////////////////////////////////////////////////////////////
-//                                                                       //
-// NOTICE OF COPYRIGHT                                                   //
-//                                                                       //
-// Moodle - Modular Object-Oriented Dynamic Learning Environment         //
-//          http://moodle.com                                            //
-//                                                                       //
-// 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 2 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                         //
-//                                                                       //
-///////////////////////////////////////////////////////////////////////////
+// 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/>.
 
 /**
- * Base message output class
+ * Contains a base class for extension by message processors
  *
- * @author Luis Rodrigues
- * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
- * @package
+ * @package   core_message
+ * @copyright Luis Rodrigues
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
-
 /**
- * Base message output class
+ * Base message processor class for extension by message processors
+ *
+ * @package   core_message
+ * @copyright 2008 Luis Rodrigues
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 abstract class message_output {
+    /**
+     * Process a message received by a user
+     *
+     * @see message_send()
+     * @param stdClass $message The event data submitted by the message provider to message_send() plus $eventdata->savedmessageid
+     */
     public abstract function send_message($message);
-    public abstract function process_form($form, &$preferences);
+
+    /**
+     * Load the config data from database to put on the config form on the messaging preferences page
+     *
+     * @param array $preferences Array of user preferences
+     * @param int $userid The user ID
+     */
     public abstract function load_data(&$preferences, $userid);
+
+    /**
+     * Create necessary fields in the config form on the messaging preferences page
+     *
+     * @param array $preferences An array of user preferences
+     */
     public abstract function config_form($preferences);
+
     /**
-     * @return bool have all the necessary config settings been
-     * made that allow this plugin to be used.
+     * Parse the submitted form and save data into an array of user preferences
+     *
+     * @param stdClass $form preferences form class
+     * @param array $preferences preferences array
+     */
+    public abstract function process_form($form, &$preferences);
+    
+    /**
+     * Are the message processor's system settings configured?
+     *
+     * @return bool True if all necessary config settings been entered
      */
     public function is_system_configured() {
         return true;
     }
+
     /**
-     * @param  object $user the user object, defaults to $USER.
-     * @return bool has the user made all the necessary settings
-     * in their profile to allow this plugin to be used.
+     * Are the message processor's user specific settings configured?
+     *
+     * @param  stdClass $user the user object, defaults to $USER.
+     * @return bool True if the user has all necessary settings in their messaging preferences
      */
     public function is_user_configured($user = null) {
         return true;
     }
 
     /**
-     * @return int the Default message output settings for this output, for
-     * message providers that do not specify what the settings should be for
-     * this output in the messages.php file.
+     * Returns the message processors default settings
+     * Should the processor be enabled for logged in users by default?
+     * Should the processor be enabled for logged off users by default?
+     * Is enabling it disallowed, permitted or forced?
+     *
+     * @return int The Default message output settings expressed as a bit mask
+     *         MESSAGE_DEFAULT_LOGGEDIN + MESSAGE_DEFAULT_LOGGEDOFF + MESSAGE_DISALLOWED|MESSAGE_PERMITTED|MESSAGE_FORCED
      */
     public function get_default_messaging_settings() {
         return MESSAGE_PERMITTED;
index 7fee432..ad81798 100644 (file)
@@ -1,5 +1,30 @@
 <?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/>.
 
+/**
+ * Installation code for the popup message processor
+ *
+ * @package   message_popup
+ * @copyright 2009 Dongsheng Cai <dongsheng@moodle.com>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Install the popup message processor
+ */
 function xmldb_message_popup_install() {
     global $DB;
 
index 94d0621..63a4f73 100644 (file)
@@ -1,36 +1,32 @@
 <?php
-
-///////////////////////////////////////////////////////////////////////////
-//                                                                       //
-// NOTICE OF COPYRIGHT                                                   //
-//                                                                       //
-// Moodle - Modular Object-Oriented Dynamic Learning Environment         //
-//          http://moodle.com                                            //
-//                                                                       //
-// 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 2 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                         //
-//                                                                       //
-///////////////////////////////////////////////////////////////////////////
+// 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/>.
 
 /**
  * Upgrade code for popup message processor
  *
- * @author Luis Rodrigues
- * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
- * @package
+ * @package   message_popup
+ * @copyright 2008 Luis Rodrigues
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU Public License
  */
 
+/**
+ * Upgrade code for the popup message processor
+ *
+ * @param int $oldversion The version that we are upgrading from
+ */
 function xmldb_message_popup_upgrade($oldversion) {
     global $CFG, $DB;
 
index bbe0920..911040e 100644 (file)
@@ -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,7 +15,7 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Strings for component 'message_popup', language 'en', branch 'MOODLE_20_STABLE'
+ * Strings for component 'message_popup', language 'en'
  *
  * @package   message_popup
  * @copyright 1999 onwards Martin Dougiamas  {@link http://moodle.com}
index feb6c43..dd16ff3 100644 (file)
@@ -1,38 +1,29 @@
 <?php
-
-///////////////////////////////////////////////////////////////////////////
-//                                                                       //
-// NOTICE OF COPYRIGHT                                                   //
-//                                                                       //
-// Moodle - Modular Object-Oriented Dynamic Learning Environment         //
-//          http://moodle.com                                            //
-//                                                                       //
-// 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 2 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                         //
-//                                                                       //
-///////////////////////////////////////////////////////////////////////////
+// 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/>.
 
 /**
  * Popup message processor - lib file
  *
- * @author Luis Rodrigues
- * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
- * @package
+ * @package   message_popup
+ * @copyright 2008 Luis Rodrigues
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU Public License
  */
 
 /**
- * Register the processor.
+ * Register the popup message processor
  */
 function popup_install(){
     global $DB;
index fdb3692..68886ec 100644 (file)
@@ -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
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Popup message processor - stores the message to be shown using the message popup
+ * Popup message processor, stores messages to be shown using the message popup
  *
- * @copyright Luis Rodrigues
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v2 or later
- * @package message
+ * @package   message_popup
+ * @copyright 2008 Luis Rodrigues
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v2 or later
  */
 
 require_once(dirname(dirname(dirname(dirname(__FILE__)))) . '/config.php'); //included from messagelib (how to fix?)
 require_once($CFG->dirroot.'/message/output/lib.php');
 
+/**
+ * The popup message processor
+ *
+ * @package   message_popup
+ * @copyright 2008 Luis Rodrigues and Martin Dougiamas
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class message_output_popup extends message_output{
 
     /**
@@ -59,15 +65,33 @@ class message_output_popup extends message_output{
         return true;
     }
 
+    /**
+     * Creates necessary fields in the messaging config form.
+     *
+     * @param array $preferences An array of user preferences
+     */
     function config_form($preferences) {
         return null;
     }
 
+    /**
+     * Parses the submitted form data and saves it into preferences array.
+     *
+     * @param stdClass $form preferences form class
+     * @param array $preferences preferences array
+     */
     public function process_form($form, &$preferences) {
         return true;
     }
+
+    /**
+     * Loads the config data from database to put on the form during initial form display
+     *
+     * @param array $preferences preferences array
+     * @param int $userid the user id
+     */
     public function load_data(&$preferences, $userid) {
         global $USER;
         return true;
     }
-}
\ No newline at end of file
+}
index ffaa0fc..fa2fbbc 100644 (file)
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Popup processor version information
+ * Popup message processor version information
  *
- * @package    message
- * @subpackage popup
- * @author     Luis Rodrigues
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package   message_popup
+ * @copyright 2008 Luis Rodrigues
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
index d941c95..0e50c46 100644 (file)
@@ -15,9 +15,9 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Messaging libraries
+ * Contains renderer objects for messaging
  *
- * @package    message
+ * @package    core_message
  * @copyright  2011 Lancaster University Network Services Limited
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -29,7 +29,8 @@ defined('MOODLE_INTERNAL') || die();
  *
  * Class for rendering various message objects
  *
- * @package    message
+ * @package    core_message
+ * @subpackage message
  * @copyright  2011 Lancaster University Network Services Limited
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -38,8 +39,8 @@ class core_message_renderer extends plugin_renderer_base {
     /**
      * Display the interface to manage message outputs
      *
-     * @param   mixed   $processors array of objects containing message processors
-     * @return  string              The text to render
+     * @param  array  $processors array of objects containing message processors
+     * @return string The text to render
      */
     public function manage_messageoutputs($processors) {
         global $CFG;
@@ -106,10 +107,10 @@ class core_message_renderer extends plugin_renderer_base {
     /**
      * Display the interface to manage default message outputs
      *
-     * @param   mixed   $processors  array of objects containing message processors
-     * @param   mixed   $providers   array of objects containing message providers
-     * @param   mixed   $preferences array of objects containing current preferences
-     * @return  string               The text to render
+     * @param  array $processors  array of objects containing message processors
+     * @param  array $providers   array of objects containing message providers
+     * @param  array $preferences array of objects containing current preferences
+     * @return string The text to render
      */
     public function manage_defaultmessageoutputs($processors, $providers, $preferences) {
         global $CFG;
@@ -206,13 +207,12 @@ class core_message_renderer extends plugin_renderer_base {
     /**
      * Display the interface for messaging options
      *
-     * @param   mixed   $processors         array of objects containing message processors
-     * @param   mixed   $providers          array of objects containing message providers
-     * @param   mixed   $preferences        array of objects containing current preferences
-     * @param   mixed   $defaultpreferences array of objects containing site default preferences
-     * $param   boolean $notificationsdisabled indicates whether the user's "emailstop" flag is
-     *                                      set so shouldn't receive any non-forced notifications
-     * @return  string                      The text to render
+     * @param array $processors Array of objects containing message processors
+     * @param array $providers Array of objects containing message providers
+     * @param array $preferences Array of objects containing current preferences
+     * @param array $defaultpreferences Array of objects containing site default preferences
+     * @param bool $notificationsdisabled Indicate if the user's "emailstop" flag is set (shouldn't receive any non-forced notifications)
+     * @return string The text to render
      */
     public function manage_messagingoptions($processors, $providers, $preferences, $defaultpreferences, $notificationsdisabled = false) {
         // Filter out enabled, available system_configured and user_configured processors only.
index 88dd4b2..6390c46 100644 (file)
@@ -1,13 +1,44 @@
 <?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/>.
+
+/**
+ * Contains the definition of the form used to send messages
+ *
+ * @package    core_message
+ * @copyright  2009 Sam Hemelryk
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 if (!defined('MOODLE_INTERNAL')) {
     die('Direct access to this script is forbidden.');    ///  It must be included from a Moodle page
 }
 
 require_once($CFG->dirroot.'/lib/formslib.php');
 
+/**
+ * The form used by users to send instant messages
+ *
+ * @package   core_message
+ * @copyright 2009 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class send_form extends moodleform {
 
+    /**
+     * Define the mform elements required
+     */
     function definition () {
 
         $mform =& $this->_form;
@@ -32,7 +63,7 @@ class send_form extends moodleform {
     /**
      * Used to structure incoming data for the message editor component
      *
-     * @param <type> $data
+     * @param array $data
      */
     function set_data($data) {