MDL-30980 core: Php document updated for string api
authorRajesh Taneja <rajesh@moodle.org>
Thu, 12 Jan 2012 07:01:18 +0000 (15:01 +0800)
committerRajesh Taneja <rajesh@moodle.com>
Tue, 7 Feb 2012 06:35:47 +0000 (14:35 +0800)
lib/moodlelib.php
lib/textlib.class.php

index e4062fe..153ed68 100644 (file)
@@ -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 '</h1>';
  * </code>
  *
+ * @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
  */
index 9702738..6403504 100644 (file)
@@ -15,8 +15,9 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
+ * 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) {