Browse files

Updating phpdoc comments to Rajesh's specifications.

  • Loading branch information...
1 parent 5fc420e commit 4d6b40a0200ab0d2003d08a97b01043dc109c770 Gerard (Gerry) Caulfield committed Jan 23, 2012
Showing with 78 additions and 66 deletions.
  1. +7 −10 lib/ajax/ajaxlib.php
  2. +23 −28 lib/ajax/setuserpref.php
  3. +48 −28 lib/moodlelib.php
View
17 lib/ajax/ajaxlib.php
@@ -1,5 +1,4 @@
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@@ -25,16 +24,14 @@
*/
/**
- * You need to call this function if you wish to use the set_user_preference
- * method in javascript_static.php, to white-list the preference you want to update
- * from JavaScript, and to specify the type of cleaning you expect to be done on
- * values.
+ * You need to call this function if you wish to use the set_user_preference method in javascript_static.php, to white-list the
+ * preference you want to update from JavaScript, and to specify the type of cleaning you expect to be done on values.
*
- * @param string $name the name of the user_perference we should allow to be
- * updated by remote calls.
- * @param integer $paramtype one of the PARAM_{TYPE} constants, user to clean
- * submitted values before set_user_preference is called.
- * @return void
+ * @package core_preference
+ * @category preference
+ * @param string $name the name of the user_perference we should allow to be updated by remote calls.
+ * @param integer $paramtype one of the PARAM_{TYPE} constants, user to clean submitted values before set_user_preference is called.
+ * @return null
*/
function user_preference_allow_ajax_update($name, $paramtype) {
global $USER, $PAGE;
View
51 lib/ajax/setuserpref.php
@@ -1,35 +1,30 @@
<?php
-
-///////////////////////////////////////////////////////////////////////////
-// //
-// NOTICE OF COPYRIGHT //
-// //
-// Moodle - Modular Object-Oriented Dynamic Learning Environment //
-// http://moodle.org //
-// //
-// Copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.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/>.
+
+
/**
- * Code to update a user preference in response to an ajax call. You should not
- * send requests to this script directly. Instead use the set_user_preference
+ * Code to update a user preference in response to an ajax call.
+ *
+ * You should not send requests to this script directly. Instead use the set_user_preference
* function in javascript_static.js.
*
- * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
- * @package moodlecore
+ * @package core_preference
+ * @category preference
+ * @copyright Copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com
+ * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
*/
require_once(dirname(__FILE__) . '/../../config.php');
View
76 lib/moodlelib.php
@@ -1,5 +1,4 @@
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@@ -1558,17 +1557,21 @@ function gc_cache_flags() {
return true;
}
-/// FUNCTIONS FOR HANDLING USER PREFERENCES ////////////////////////////////////
+// USER PREFERENCE API
/**
* Refresh user preference cache. This is used most often for $USER
* object that is stored in session, but it also helps with performance in cron script.
*
* Preferences for each user are loaded on first use on every page, then again after the timeout expires.
*
- * @param stdClass $user user object, preferences are preloaded into ->preference property
- * @param int $cachelifetime cache life time on the current page (ins seconds)
- * @return void
+ * @package core
+ * @category preference
+ * @access public
+ * @param stdClass $user User object. Preferences are preloaded into 'preference' property
+ * @param int $cachelifetime Cache life time on the current page (in seconds)
+ * @throws coding_exception
+ * @return null
*/
function check_user_preferences_loaded(stdClass $user, $cachelifetime = 120) {
global $DB;
@@ -1608,13 +1611,14 @@ function check_user_preferences_loaded(stdClass $user, $cachelifetime = 120) {
}
/**
- * Called from set/delete_user_preferences, so that the prefs can
+ * Called from set/unset_user_preferences, so that the prefs can
* be correctly reloaded in different sessions.
*
* NOTE: internal function, do not call from other code.
*
- * @param integer $userid the user whose prefs were changed.
- * @return void
+ * @package core
+ * @access private
+ * @param integer $userid the user whose prefs were changed.
*/
function mark_user_preferences_changed($userid) {
global $CFG;
@@ -1630,13 +1634,17 @@ function mark_user_preferences_changed($userid) {
/**
* Sets a preference for the specified user.
*
- * If user object submitted, 'preference' property contains the preferences cache.
+ * If a $user object is submitted it's 'preference' property is used for the preferences cache.
*
- * @param string $name The key to set as preference for the specified user
- * @param string $value The value to set for the $name key in the specified user's record,
- * null means delete current value
- * @param stdClass|int $user A moodle user object or id, null means current user
- * @return bool always true or exception
+ * @package core
+ * @category preference
+ * @access public
+ * @param string $name The key to set as preference for the specified user
+ * @param string $value The value to set for the $name key in the specified user's
+ * record, null means delete current value.
+ * @param stdClass|int|null $user A moodle user object or id, null means current user
+ * @throws coding_exception
+ * @return bool Always true or exception
*/
function set_user_preference($name, $value, $user = null) {
global $USER, $DB;
@@ -1703,11 +1711,14 @@ function set_user_preference($name, $value, $user = null) {
/**
* Sets a whole array of preferences for the current user
*
- * If user object submitted, 'preference' property contains the preferences cache.
+ * If a $user object is submitted it's 'preference' property is used for the preferences cache.
*
- * @param array $prefarray An array of key/value pairs to be set
- * @param stdClass|int $user A moodle user object or id, null means current user
- * @return bool always true or exception
+ * @package core
+ * @category preference
+ * @access public
+ * @param array $prefarray An array of key/value pairs to be set
+ * @param stdClass|int|null $user A moodle user object or id, null means current user
+ * @return bool Always true or exception
*/
function set_user_preferences(array $prefarray, $user = null) {
foreach ($prefarray as $name => $value) {
@@ -1719,11 +1730,15 @@ function set_user_preferences(array $prefarray, $user = null) {
/**
* Unsets a preference completely by deleting it from the database
*
- * If user object submitted, 'preference' property contains the preferences cache.
+ * If a $user object is submitted it's 'preference' property is used for the preferences cache.
*
- * @param string $name The key to unset as preference for the specified user
- * @param stdClass|int $user A moodle user object or id, null means current user
- * @return bool always true or exception
+ * @package core
+ * @category preference
+ * @access public
+ * @param string $name The key to unset as preference for the specified user
+ * @param stdClass|int|null $user A moodle user object or id, null means current user
+ * @throws coding_exception
+ * @return bool Always true or exception
*/
function unset_user_preference($name, $user = null) {
global $USER, $DB;
@@ -1773,12 +1788,17 @@ function unset_user_preference($name, $user = null) {
* none is found, then the optional value $default is returned,
* otherwise NULL.
*
- * If user object submitted, 'preference' property contains the preferences cache.
- *
- * @param string $name Name of the key to use in finding a preference value
- * @param mixed $default Value to be returned if the $name key is not set in the user preferences
- * @param stdClass|int $user A moodle user object or id, null means current user
- * @return mixed string value or default
+ * If a $user object is submitted it's 'preference' property is used for the preferences cache.
+ *
+ * @package core
+ * @category preference
+ * @access public
+ * @param string $name Name of the key to use in finding a preference value
+ * @param mixed|null $default Value to be returned if the $name key is not set in the user preferences
+ * @param stdClass|int|null $user A moodle user object or id, null means current user
+ * @throws coding_exception
+ * @return string|mixed|null A string containing the value of a single preference. An
+ * array with all of the preferences or null
*/
function get_user_preferences($name = null, $default = null, $user = null) {
global $USER;

0 comments on commit 4d6b40a

Please sign in to comment.