From 55d1f2727c70648a83b89fbc6df7d06acf5e404e Mon Sep 17 00:00:00 2001 From: Rajesh Taneja Date: Thu, 12 Jan 2012 15:01:18 +0800 Subject: [PATCH] MDL-30980 core: Php document updated for string api --- lib/moodlelib.php | 81 +++++++++++++++++++++-------------- lib/textlib.class.php | 98 +++++++++++++++++++++++++------------------ 2 files changed, 107 insertions(+), 72 deletions(-) diff --git a/lib/moodlelib.php b/lib/moodlelib.php index e4062fe1cd6..153ed6832b4 100644 --- a/lib/moodlelib.php +++ b/lib/moodlelib.php @@ -5895,6 +5895,7 @@ function clean_filename($string) { /** * Returns the code for the current language * + * @category string * @return string */ function current_language() { @@ -5924,6 +5925,7 @@ function current_language() { /** * Returns parent language of current active language if defined * + * @category string * @uses COURSE * @uses SESSION * @param string $lang null means current language @@ -5960,6 +5962,7 @@ function get_parent_language($lang=null) { * The param $forcereload is needed for CLI installer only where the string_manager instance * must be replaced during the install.php script life time. * + * @category string * @param bool $forcereload shall the singleton be released and new instance created instead? * @return string_manager */ @@ -6005,10 +6008,12 @@ function get_string_manager($forcereload=false) { /** + * Interface for string manager + * * Interface describing class which is responsible for getting * of localised strings from language packs. * - * @package moodlecore + * @package core * @copyright 2010 Petr Skoda (http://skodak.org) * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -6058,11 +6063,11 @@ interface string_manager { public function get_list_of_languages($lang = NULL, $standard = 'iso6392'); /** - * Does the translation exist? + * Checks if the translation exists for the language * * @param string $lang moodle translation language code - * @param bool include also disabled translations? - * @return boot true if exists + * @param bool $includeall include also disabled translations + * @return bool true if exists */ public function translation_exists($lang, $includeall = true); @@ -6101,7 +6106,10 @@ interface string_manager { /** * Standard string_manager implementation * - * @package moodlecore + * Implements string_manager with getting and printing localised strings + * + * @package core + * @category string * @copyright 2010 Petr Skoda (http://skodak.org) * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -6122,7 +6130,7 @@ class core_string_manager implements string_manager { protected $countdiskcache = 0; /** @var bool use disk cache */ protected $usediskcache; - /* @var array limit list of translations */ + /** @var array limit list of translations */ protected $translist; /** @var string location of a file that caches the list of available translations */ protected $menucache; @@ -6148,6 +6156,7 @@ class core_string_manager implements string_manager { /** * Returns dependencies of current language, en is not included. + * * @param string $lang * @return array all parents, the lang itself is last */ @@ -6172,6 +6181,7 @@ class core_string_manager implements string_manager { /** * Load all strings for one component + * * @param string $component The module the string is associated with * @param string $lang * @param bool $disablecache Do not use caches, force fetching the strings from sources @@ -6294,8 +6304,7 @@ class core_string_manager implements string_manager { * * get_string() is throwing debug warnings, sometimes we do not want them * or we want to display better explanation of the problem. - * - * Use with care! + * Note: Use with care! * * @param string $identifier The identifier of the string to search for * @param string $component The module the string is associated with @@ -6418,6 +6427,7 @@ class core_string_manager implements string_manager { /** * Returns information about the string_manager performance + * * @return array */ public function get_performance_summary() { @@ -6515,11 +6525,11 @@ class core_string_manager implements string_manager { } /** - * Does the translation exist? + * Checks if the translation exists for the language * * @param string $lang moodle translation language code - * @param bool include also disabled translations? - * @return boot true if exists + * @param bool $includeall include also disabled translations + * @return bool true if exists */ public function translation_exists($lang, $includeall = true) { @@ -6541,6 +6551,7 @@ class core_string_manager implements string_manager { /** * Returns localised list of installed translations + * * @param bool $returnall return all or just enabled * @return array moodle translation code => localised translation name */ @@ -6669,11 +6680,13 @@ class core_string_manager implements string_manager { /** + * Fetches minimum strings for installation + * * Minimalistic string fetching implementation * that is used in installer before we fetch the wanted * language pack from moodle.org lang download site. * - * @package moodlecore + * @package core * @copyright 2010 Petr Skoda (http://skodak.org) * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -6829,11 +6842,11 @@ class install_string_manager implements string_manager { } /** - * Does the translation exist? + * Checks if the translation exists for the language * * @param string $lang moodle translation language code - * @param bool include also disabled translations? - * @return boot true if exists + * @param bool $includeall include also disabled translations + * @return bool true if exists */ public function translation_exists($lang, $includeall = true) { return file_exists($this->installroot.'/'.$lang.'/langconfig.php'); @@ -6941,6 +6954,7 @@ class install_string_manager implements string_manager { * But you should never do that anyway! * For more information {@see lang_string} * + * @category string * @param string $identifier The key identifier for the localized string * @param string $component The module where the key identifier is stored, * usually expressed as the filename in the language pack without the @@ -7012,8 +7026,8 @@ function get_string($identifier, $component = '', $a = NULL, $lazyload = false) * Converts an array of strings to their localized value. * * @param array $array An array of strings - * @param string $module The language module that these strings can be found in. - * @return array and array of translated strings. + * @param string $component The language module that these strings can be found in. + * @return stdClass translated strings. */ function get_strings($array, $component = '') { $string = new stdClass; @@ -7042,9 +7056,10 @@ function get_strings($array, $component = '') { * echo ''; * * + * @category string * @param string $identifier The key identifier for the localized string * @param string $component The module where the key identifier is stored. If none is specified then moodle.php is used. - * @param mixed $a An object, string or number that can be used within translation strings + * @param string|object|array $a An object, string or number that can be used within translation strings */ function print_string($identifier, $component = '', $a = NULL) { echo get_string($identifier, $component, $a); @@ -8604,9 +8619,7 @@ function upgrade_set_timeout($max_execution_time=300) { /** * Sets the system locale * - * @todo Finish documenting this function - * - * @global object + * @category string * @param string $locale Can be used to force a locale */ function moodle_setlocale($locale='') { @@ -8664,8 +8677,9 @@ function moodle_setlocale($locale='') { /** * Converts string to lowercase using most compatible function available. * - * @todo Remove this function when no longer in use - * @deprecated Use textlib->strtolower($text) instead. + * @deprecated since Moodle 2.0 use textlib::strtolower() + * @todo MDL-31250 Remove this function when no longer in use + * @see textlib::strtolower($text) * * @param string $string The string to convert to all lowercase characters. * @param string $encoding The encoding on the string. @@ -8688,6 +8702,7 @@ function moodle_strtolower ($string, $encoding='') { * * Words are defined as things between whitespace. * + * @category string * @param string $string The text to be searched for words. * @return int The count of words in the specified string */ @@ -8700,6 +8715,7 @@ function count_words($string) { * * Letters are defined as chars not in tags and different from whitespace. * + * @category string * @param string $string The text to be searched for letters. * @return int The count of letters in the specified text. */ @@ -8760,12 +8776,13 @@ function complex_random_string($length=null) { * Given some text (which may contain HTML) and an ideal length, * this function truncates the text neatly on a word boundary if possible * - * @global object - * @param string $text - text to be shortened - * @param int $ideal - ideal string length + * @category string + * @global stdClass $CFG + * @param string $text text to be shortened + * @param int $ideal ideal string length * @param boolean $exact if false, $text will not be cut mid-word * @param string $ending The string to append if the passed string is truncated - * @return string $truncate - shortened string + * @return string $truncate shortened string */ function shorten_text($text, $ideal=30, $exact = false, $ending='...') { @@ -8919,7 +8936,7 @@ function getweek ($startdate, $thedate) { * {@link http://www.phpbuilder.com/columns/jesus19990502.php3} and * {@link http://es2.php.net/manual/en/function.str-shuffle.php#73254} * - * @global object + * @global stdClass $CFG * @param int $maxlen The maximum size of the password being generated. * @return string */ @@ -8984,7 +9001,7 @@ function generate_password($maxlen=10) { * Localized floats must not be used in calculations! * * @param float $float The float to print - * @param int $places The number of decimal places to print. + * @param int $decimalpoints The number of decimal places to print. * @param bool $localized use localized decimal separator * @return string locale float */ @@ -9003,7 +9020,7 @@ function format_float($float, $decimalpoints=1, $localized=true) { * Converts locale specific floating point/comma number back to standard PHP float value * Do NOT try to do any math operations before this conversion on any user submitted floats! * - * @param string $locale_float locale aware float representation + * @param string $locale_float locale aware float representation * @return float */ function unformat_float($locale_float) { @@ -10562,8 +10579,8 @@ function get_home_page() { * 1. You cannot use a lang_string object as an array offset. Doing so will * result in PHP throwing an error. (You can use it as an object property!) * - * @package moodlecore - * + * @package core + * @category string * @copyright 2011 Sam Hemelryk * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ diff --git a/lib/textlib.class.php b/lib/textlib.class.php index 97027389308..6403504e51b 100644 --- a/lib/textlib.class.php +++ b/lib/textlib.class.php @@ -15,8 +15,9 @@ // along with Moodle. If not, see . /** + * Defines string apis + * * @package core - * @subpackage lib * @copyright (C) 2001-3001 Eloy Lafuente (stronk7) {@link http://contiento.com} * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -27,7 +28,9 @@ defined('MOODLE_INTERNAL') || die(); * Original singleton helper function, please use static methods instead, * ex: textlib::convert() * - * @deprecated + * @deprecated since Moodle 2.1 MDL-29027 textlib contains static functions + * @todo MDL-31301 calling of textlib functions should be static. + * @see textlib * @return textlib instance */ function textlib_get_instance() { @@ -36,6 +39,8 @@ function textlib_get_instance() { /** + * defines string api's for manipulating strings + * * This class is used to manipulate strings under Moodle 1.6 an later. As * utf-8 text become mandatory a pool of safe functions under this encoding * become necessary. The name of the methods is exactly the @@ -50,15 +55,16 @@ function textlib_get_instance() { * its capabilities so, don't forget to make the conversion * from every wrapper function! * - * @package core - * @subpackage lib + * @package core + * @category string * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class textlib { /** - * Return t3lib helper class + * Return t3lib helper class, which is used for conversion between charsets + * * @return t3lib_cs */ protected static function typo3() { @@ -184,11 +190,11 @@ class textlib { /** * Multibyte safe substr() function, uses mbstring or iconv for UTF-8, falls back to typo3. * - * @param string $text + * @param string $text string to truncate * @param int $start negative value means from end - * @param int $len + * @param int $len maximum length of characters beginning from start * @param string $charset encoding of the text - * @return string + * @return string portion of string specified by the $start and $len */ public static function substr($text, $start, $len=null, $charset='utf-8') { $charset = self::parse_charset($charset); @@ -228,7 +234,7 @@ class textlib { /** * Multibyte safe strlen() function, uses mbstring or iconv for UTF-8, falls back to typo3. * - * @param string $text + * @param string $text input string * @param string $charset encoding of the text * @return int number of characters */ @@ -253,7 +259,7 @@ class textlib { /** * Multibyte safe strtolower() function, uses mbstring, falls back to typo3. * - * @param string $text + * @param string $text input string * @param string $charset encoding of the text (may not work for all encodings) * @return string lower case text */ @@ -274,7 +280,7 @@ class textlib { /** * Multibyte safe strtoupper() function, uses mbstring, falls back to typo3. * - * @param string $text + * @param string $text input string * @param string $charset encoding of the text (may not work for all encodings) * @return string upper case text */ @@ -293,12 +299,13 @@ class textlib { } /** + * Find the position of the first occurrence of a substring in a string. * UTF-8 ONLY safe strpos(), uses mbstring, falls back to iconv. * - * @param string $haystack - * @param string $needle - * @param int $offset - * @return string + * @param string $haystack the string to search in + * @param string $needle one or more charachters to search for + * @param int $offset offset from begining of string + * @return int the numeric position of the first occurrence of needle in haystack. */ public static function strpos($haystack, $needle, $offset=0) { if (function_exists('mb_strpos')) { @@ -309,11 +316,12 @@ class textlib { } /** + * Find the position of the last occurrence of a substring in a string * UTF-8 ONLY safe strrpos(), uses mbstring, falls back to iconv. * - * @param string $haystack - * @param string $needle - * @return string + * @param string $haystack the string to search in + * @param string $needle one or more charachters to search for + * @return int the numeric position of the last occurrence of needle in haystack */ public static function strrpos($haystack, $needle) { if (function_exists('mb_strpos')) { @@ -327,9 +335,9 @@ class textlib { * Try to convert upper unicode characters to plain ascii, * the returned string may contain unconverted unicode characters. * - * @param string $text + * @param string $text input string * @param string $charset encoding of the text - * @return string + * @return string converted ascii string */ public static function specialtoascii($text, $charset='utf-8') { $charset = self::parse_charset($charset); @@ -344,9 +352,9 @@ class textlib { * This function seems to be 100% compliant with RFC1342. Credits go to: * paravoid (http://www.php.net/manual/en/function.mb-encode-mimeheader.php#60283). * - * @param string $text + * @param string $text input string * @param string $charset encoding of the text - * @return string + * @return string base64 encoded header */ public static function encode_mimeheader($text, $charset='utf-8') { if (empty($text)) { @@ -432,9 +440,9 @@ class textlib { * http://php.net/manual/en/function.html-entity-decode.php#75153 * with some custom mods to provide more functionality * - * @param string $str input string - * @param boolean $htmlent convert also html entities (defaults to true) - * @return string + * @param string $str input string + * @param boolean $htmlent convert also html entities (defaults to true) + * @return string encoded UTF-8 string * * NOTE: we could have used typo3 entities_to_utf8() here * but the direct alternative used runs 400% quicker @@ -466,10 +474,10 @@ class textlib { /** * Converts all Unicode chars > 127 to numeric entities &#nnnn; or &#xnnn;. * - * @param string $str input string - * @param boolean $dec output decadic only number entities - * @param boolean $nonnum remove all non-numeric entities - * @return string converted string + * @param string $str input string + * @param boolean $dec output decadic only number entities + * @param boolean $nonnum remove all non-numeric entities + * @return string converted string */ public static function utf8_to_entities($str, $dec=false, $nonnum=false) { // Avoid some notices from Typo3 code @@ -487,9 +495,9 @@ class textlib { } /** - * Removes the BOM from unicode string - see http://unicode.org/faq/utf_bom.html + * Removes the BOM from unicode string {@link http://unicode.org/faq/utf_bom.html} * - * @param string $str + * @param string $str input string * @return string */ public static function trim_utf8_bom($str) { @@ -502,6 +510,7 @@ class textlib { /** * Returns encoding options for select boxes, utf-8 and platform encoding first + * * @return array encodings */ public static function get_encodings() { @@ -548,7 +557,7 @@ class textlib { * Makes first letter of each word capital - words must be separated by spaces. * Use with care, this function does not work properly in many locales!!! * - * @param string $text + * @param string $text input string * @return string */ public static function strtotitle($text) { @@ -596,8 +605,7 @@ class textlib { /** * A collator class with static methods that can be used for sorting. * - * @package core - * @subpackage lib + * @package core * @copyright 2011 Sam Hemelryk * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -697,6 +705,8 @@ abstract class collatorlib { * 0 if str1 is equal to str2 * -1 if str1 is less than str2 * + * @param string $str1 first string to compare + * @param string $str2 second string to compare * @return int */ public static function compare($str1, $str2) { @@ -732,11 +742,12 @@ abstract class collatorlib { } /** + * Object comparison using collator + * * Abstract class to aid the sorting of objects with respect to proper language * comparison using collator * - * @package core - * @subpackage lib + * @package core * @copyright 2011 Sam Hemelryk * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -758,10 +769,12 @@ abstract class collatorlib_comparison { } /** + * Compare properties of two objects + * * A comparison helper for comparing properties of two objects * - * @package core - * @subpackage lib + * @package core + * @category string * @copyright 2011 Sam Hemelryk * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -771,6 +784,8 @@ class collatorlib_property_comparison extends collatorlib_comparison { protected $property; /** + * Constructor + * * @param string $property */ public function __construct($property) { @@ -795,10 +810,11 @@ class collatorlib_property_comparison extends collatorlib_comparison { } /** + * Compare method of two objects + * * A comparison helper for comparing the result of a method on two objects * - * @package core - * @subpackage lib + * @package core * @copyright 2011 Sam Hemelryk * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -808,6 +824,8 @@ class collatorlib_method_comparison extends collatorlib_comparison { protected $method; /** + * Constructor + * * @param string $method The method to call against each object */ public function __construct($method) {