From 6fbd60ef5757185280498771e7c4a8dd7ac4376a Mon Sep 17 00:00:00 2001 From: Andrew Davis Date: Thu, 5 Jan 2012 12:05:02 +0700 Subject: [PATCH] MDL-30987 message: updated phpdocs for /lib/messagelib.php and /message --- lib/messagelib.php | 70 ++++++------ message/defaultoutputs.php | 8 +- message/discussion.php | 10 +- message/edit.php | 7 +- message/externallib.php | 20 +++- message/index.php | 7 +- message/lib.php | 30 ++--- message/output/email/db/install.php | 25 +++++ message/output/email/db/upgrade.php | 48 ++++---- .../output/email/lang/en/message_email.php | 9 +- message/output/email/lib.php | 47 ++++---- message/output/email/message_output_email.php | 70 ++++++------ message/output/email/settings.php | 9 +- message/output/email/version.php | 5 +- message/output/jabber/db/install.php | 26 +++++ message/output/jabber/db/upgrade.php | 48 ++++---- .../output/jabber/lang/en/message_jabber.php | 9 +- message/output/jabber/lib.php | 43 +++---- .../output/jabber/message_output_jabber.php | 68 ++++++------ message/output/jabber/settings.php | 5 +- message/output/jabber/version.php | 7 +- message/output/lib.php | 105 +++++++++++------- message/output/popup/db/install.php | 25 +++++ message/output/popup/db/upgrade.php | 48 ++++---- .../output/popup/lang/en/message_popup.php | 3 +- message/output/popup/lib.php | 45 +++----- message/output/popup/message_output_popup.php | 36 +++++- message/output/popup/version.php | 9 +- message/renderer.php | 32 +++--- message/send_form.php | 35 +++++- 30 files changed, 512 insertions(+), 397 deletions(-) diff --git a/lib/messagelib.php b/lib/messagelib.php index bbbfccf0ecbb8..4c5b5640b6447 100644 --- a/lib/messagelib.php +++ b/lib/messagelib.php @@ -1,5 +1,4 @@ . /** - * 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 @@ /** * 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 @@ * 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; diff --git a/message/defaultoutputs.php b/message/defaultoutputs.php index 4331ab5c9fea0..4d94cc4cd3164 100644 --- a/message/defaultoutputs.php +++ b/message/defaultoutputs.php @@ -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 @@ echo $OUTPUT->header(); echo $OUTPUT->heading(get_string('defaultmessageoutputs', 'message')); echo $messageoutputs; -echo $OUTPUT->footer(); \ No newline at end of file +echo $OUTPUT->footer(); diff --git a/message/discussion.php b/message/discussion.php index a588e5eb12403..0717ea4c39e37 100644 --- a/message/discussion.php +++ b/message/discussion.php @@ -1,5 +1,4 @@ . /** - * 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'); diff --git a/message/edit.php b/message/edit.php index 17e0e75b222fa..9cabdc2537c0e 100644 --- a/message/edit.php +++ b/message/edit.php @@ -1,5 +1,4 @@ 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 diff --git a/message/output/email/db/install.php b/message/output/email/db/install.php index eaa59f5e855fd..a7f26dbebb2e5 100644 --- a/message/output/email/db/install.php +++ b/message/output/email/db/install.php @@ -1,5 +1,30 @@ . +/** + * 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; diff --git a/message/output/email/db/upgrade.php b/message/output/email/db/upgrade.php index 14d7a8ad1ff11..dd79b5c6a515a 100644 --- a/message/output/email/db/upgrade.php +++ b/message/output/email/db/upgrade.php @@ -1,36 +1,32 @@ . /** * 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; diff --git a/message/output/email/lang/en/message_email.php b/message/output/email/lang/en/message_email.php index ae06d11d97660..611eca1c7a121 100644 --- a/message/output/email/lang/en/message_email.php +++ b/message/output/email/lang/en/message_email.php @@ -1,5 +1,4 @@ . /** - * 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'; diff --git a/message/output/email/lib.php b/message/output/email/lib.php index 7b5d13005f3c5..26d0754239345 100644 --- a/message/output/email/lib.php +++ b/message/output/email/lib.php @@ -1,38 +1,29 @@ . /** - * 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; diff --git a/message/output/email/message_output_email.php b/message/output/email/message_output_email.php index 80262db6e5ebc..a300b094366f7 100644 --- a/message/output/email/message_output_email.php +++ b/message/output/email/message_output_email.php @@ -1,37 +1,36 @@ . /** - * 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 @@ function send_message($eventdata) { /** * 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 @@ function config_form($preferences){ } /** - * 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 @@ function process_form($form, &$preferences){ } /** - * @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 */ diff --git a/message/output/email/settings.php b/message/output/email/settings.php index 7b7e7230769a0..240a9fb404cfa 100644 --- a/message/output/email/settings.php +++ b/message/output/email/settings.php @@ -17,10 +17,9 @@ /** * 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 @@ $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 +} diff --git a/message/output/email/version.php b/message/output/email/version.php index 55229bb0f3f40..0d8a892e8b997 100644 --- a/message/output/email/version.php +++ b/message/output/email/version.php @@ -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 */ diff --git a/message/output/jabber/db/install.php b/message/output/jabber/db/install.php index 2496094bc71f8..3ecd680885b80 100644 --- a/message/output/jabber/db/install.php +++ b/message/output/jabber/db/install.php @@ -1,4 +1,30 @@ . + +/** + * Jabber message processor installation code + * + * @package message_jabber + * @copyright 2009 Dongsheng Cai + * @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; diff --git a/message/output/jabber/db/upgrade.php b/message/output/jabber/db/upgrade.php index 48e12b3956036..d884f257a886e 100644 --- a/message/output/jabber/db/upgrade.php +++ b/message/output/jabber/db/upgrade.php @@ -1,36 +1,32 @@ . /** * 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; diff --git a/message/output/jabber/lang/en/message_jabber.php b/message/output/jabber/lang/en/message_jabber.php index e38f6999e664d..e00b6eef0dd1b 100644 --- a/message/output/jabber/lang/en/message_jabber.php +++ b/message/output/jabber/lang/en/message_jabber.php @@ -1,5 +1,4 @@ . /** - * 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'; diff --git a/message/output/jabber/lib.php b/message/output/jabber/lib.php index b5ed25865e497..c0e677f8e4ed2 100644 --- a/message/output/jabber/lib.php +++ b/message/output/jabber/lib.php @@ -1,34 +1,25 @@ . /** * 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 */ /** diff --git a/message/output/jabber/message_output_jabber.php b/message/output/jabber/message_output_jabber.php index c4dbbba1db7fd..c4c997466b6be 100644 --- a/message/output/jabber/message_output_jabber.php +++ b/message/output/jabber/message_output_jabber.php @@ -1,44 +1,43 @@ . /** - * 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 @@ function send_message($eventdata){ /** * 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 @@ function config_form($preferences){ } /** - * 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 @@ function process_form($form, &$preferences){ } /** - * 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 */ diff --git a/message/output/jabber/settings.php b/message/output/jabber/settings.php index 3f7428f786ffa..85c833fea8d79 100644 --- a/message/output/jabber/settings.php +++ b/message/output/jabber/settings.php @@ -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 @@ $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 +} diff --git a/message/output/jabber/version.php b/message/output/jabber/version.php index 7ecc5bb9d155d..f0a009d309a81 100644 --- a/message/output/jabber/version.php +++ b/message/output/jabber/version.php @@ -15,11 +15,10 @@ // along with Moodle. If not, see . /** - * 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 */ diff --git a/message/output/lib.php b/message/output/lib.php index 7d7aa3a6c08be..1860fc55acc02 100644 --- a/message/output/lib.php +++ b/message/output/lib.php @@ -1,64 +1,93 @@ . /** - * 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; diff --git a/message/output/popup/db/install.php b/message/output/popup/db/install.php index 7fee4324f14a9..ad817986dcc3a 100644 --- a/message/output/popup/db/install.php +++ b/message/output/popup/db/install.php @@ -1,5 +1,30 @@ . +/** + * Installation code for the popup message processor + * + * @package message_popup + * @copyright 2009 Dongsheng Cai + * @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; diff --git a/message/output/popup/db/upgrade.php b/message/output/popup/db/upgrade.php index 94d0621a8ff0d..63a4f73d4fbf5 100644 --- a/message/output/popup/db/upgrade.php +++ b/message/output/popup/db/upgrade.php @@ -1,36 +1,32 @@ . /** * 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; diff --git a/message/output/popup/lang/en/message_popup.php b/message/output/popup/lang/en/message_popup.php index bbe0920279222..911040e66e4c1 100644 --- a/message/output/popup/lang/en/message_popup.php +++ b/message/output/popup/lang/en/message_popup.php @@ -1,5 +1,4 @@ . /** - * 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} diff --git a/message/output/popup/lib.php b/message/output/popup/lib.php index feb6c43a2cc32..dd16ff3f49037 100644 --- a/message/output/popup/lib.php +++ b/message/output/popup/lib.php @@ -1,38 +1,29 @@ . /** * 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; diff --git a/message/output/popup/message_output_popup.php b/message/output/popup/message_output_popup.php index fdb3692d8b390..68886ec83fbcd 100644 --- a/message/output/popup/message_output_popup.php +++ b/message/output/popup/message_output_popup.php @@ -1,5 +1,4 @@ . /** - * 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 @@ public function send_message($eventdata) { 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 +} diff --git a/message/output/popup/version.php b/message/output/popup/version.php index ffaa0fc313667..fa2fbbca68d82 100644 --- a/message/output/popup/version.php +++ b/message/output/popup/version.php @@ -15,12 +15,11 @@ // along with Moodle. If not, see . /** - * 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(); diff --git a/message/renderer.php b/message/renderer.php index d941c9523a6e8..0e50c466a80c4 100644 --- a/message/renderer.php +++ b/message/renderer.php @@ -15,9 +15,9 @@ // along with Moodle. If not, see . /** - * 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 @@ * * 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 @@ public function manage_messageoutputs($processors) { /** * 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 @@ public function manage_defaultmessageoutputs($processors, $providers, $preferenc /** * 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. diff --git a/message/send_form.php b/message/send_form.php index 88dd4b2e0d7b7..6390c46a4e974 100644 --- a/message/send_form.php +++ b/message/send_form.php @@ -1,13 +1,44 @@ . + +/** + * 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 @@ function definition () { /** * Used to structure incoming data for the message editor component * - * @param $data + * @param array $data */ function set_data($data) {