From d3af5f253b80793b10fa29c2be60bf50208ccc27 Mon Sep 17 00:00:00 2001
From: "mariano.iglesias"
 <mariano.iglesias@3807eeeb-6ff5-0310-8944-8be069107fe0>
Date: Mon, 21 May 2007 19:38:39 +0000
Subject: [PATCH] Adding comments to code

git-svn-id: https://svn.cakephp.org/repo/branches/1.2.x.x@5147 3807eeeb-6ff5-0310-8944-8be069107fe0
---
 cake/libs/i18n.php        | 43 +++++++++++++++++++--------------------
 cake/libs/inflector.php   | 25 ++++++++++++++++++-----
 cake/libs/l10n.php        |  9 ++++----
 cake/libs/neat_string.php | 20 ++++++++++++------
 cake/libs/object.php      | 20 ++++++++++--------
 5 files changed, 71 insertions(+), 46 deletions(-)

diff --git a/cake/libs/i18n.php b/cake/libs/i18n.php
index ac9fc1730..e2a47d414 100644
--- a/cake/libs/i18n.php
+++ b/cake/libs/i18n.php
@@ -91,17 +91,16 @@ class I18n extends Object {
 		return $instance[0];
 	}
 /**
- *
  * Used by the translation functions in basics.php
  * Can also be used like I18n::translate(); but only if the uses('i18n'); has been used to load the class.
  *
- * @param string $singular
- * @param string $plural
- * @param string $domain
- * @param string $category
- * @param integer $count
- * @param string $directory
- * @return translated strings.
+ * @param string $singular String to translate
+ * @param string $plural Plural string (if any)
+ * @param string $domain Domain
+ * @param string $category Category
+ * @param integer $count Count
+ * @param string $directory Directory that contains the file that is requesting translation
+ * @return string translated strings.
  * @access public
  */
 	function translate($singular, $plural = null, $domain = null, $category = 5, $count = null, $directory = null) {
@@ -173,9 +172,9 @@ class I18n extends Object {
 /**
  * Attempts to find the plural form of a string.
  *
- * @param string $type
- * @param integrer $n
- * @return plural match
+ * @param string $type Type
+ * @param integrer $n Number
+ * @return integer plural match
  * @access private
  */
 	function __pluralGuess(&$type, $n) {
@@ -301,8 +300,9 @@ class I18n extends Object {
  * Binds the given domain to a file in the specified directory.
  * If directory is null, will attempt to search default locations.
  *
- * @param string $domain
- * @return string
+ * @param string $domain Domain to bind
+ * @param string $directory Directory
+ * @return string Domain binded
  * @access private
  */
 	function __bindTextDomain($domain, $directory = null) {
@@ -368,11 +368,10 @@ class I18n extends Object {
 		return($domain);
 	}
 /**
- *
  * Loads the binary .mo file for translation and sets the values for this translation in the var I18n::__domains
  *
- * @param resource $file
- * @param string $domain
+ * @param resource $file Binary .mo file to load
+ * @param string $domain Domain where to load file in
  * @access private
  */
 	function __loadMo($file, $domain) {
@@ -412,9 +411,9 @@ class I18n extends Object {
 /**
  * Loads the text .po file for translation and sets the values for this translation in the var I18n::__domains
  *
- * @param resource $file
- * @param string $domain
- * @return unknown
+ * @param resource $file Text .po file to load
+ * @param string $domain Domain to load file in
+ * @return array Binded domain elements
  * @access private
  */
 	function __loadPo($file, $domain) {
@@ -484,9 +483,9 @@ class I18n extends Object {
 /**
  * Not implemented
  *
- * @param string $domain
- * @param string $codeset
- * @return unknown
+ * @param string $domain Domain
+ * @param string $codeset Code set
+ * @return string
  * @access private
  * @todo Not implemented
  */
diff --git a/cake/libs/inflector.php b/cake/libs/inflector.php
index f42497f03..d20a1a4b7 100644
--- a/cake/libs/inflector.php
+++ b/cake/libs/inflector.php
@@ -56,6 +56,7 @@ class Inflector extends Object {
  * Gets a reference to the Inflector object instance
  *
  * @return object
+ * @access public
  */
 	function &getInstance() {
 		static $instance = array();
@@ -70,7 +71,6 @@ class Inflector extends Object {
  * Initializes plural inflection rules
  *
  * @access protected
- * @return void
  */
 	function __initPluralRules() {
 		$_this =& Inflector::getInstance();
@@ -156,6 +156,8 @@ class Inflector extends Object {
  *
  * @param string $word Word in singular
  * @return string Word in plural
+ * @access public
+ * @static
  */
 	function pluralize($word) {
 
@@ -199,7 +201,6 @@ class Inflector extends Object {
  * Initializes singular inflection rules
  *
  * @access protected
- * @return void
  */
 	function __initSingularRules() {
 
@@ -295,6 +296,8 @@ class Inflector extends Object {
  *
  * @param string $word Word in plural
  * @return string Word in singular
+ * @access public
+ * @static
  */
 	function singularize($word) {
 
@@ -339,6 +342,8 @@ class Inflector extends Object {
  *
  * @param string $lower_case_and_underscored_word Word to camelize
  * @return string Camelized word. likeThis.
+ * @access public
+ * @static
  */
 	function camelize($lowerCaseAndUnderscoredWord) {
 		$replace = str_replace(" ", "", ucwords(str_replace("_", " ", $lowerCaseAndUnderscoredWord)));
@@ -349,6 +354,8 @@ class Inflector extends Object {
  *
  * @param string $camel_cased_word Camel-cased word to be "underscorized"
  * @return string Underscore-syntaxed version of the $camel_cased_word
+ * @access public
+ * @static
  */
 	function underscore($camelCasedWord) {
 		$replace = strtolower(preg_replace('/(?<=\\w)([A-Z])/', '_\\1', $camelCasedWord));
@@ -360,6 +367,8 @@ class Inflector extends Object {
  *
  * @param string $lower_case_and_underscored_word String to be made more readable
  * @return string Human-readable string
+ * @access public
+ * @static
  */
 	function humanize($lowerCaseAndUnderscoredWord) {
 		$replace = ucwords(str_replace("_", " ", $lowerCaseAndUnderscoredWord));
@@ -370,6 +379,8 @@ class Inflector extends Object {
  *
  * @param string $class_name Name of class to get database table name for
  * @return string Name of the database table for given class
+ * @access public
+ * @static
  */
 	function tableize($className) {
 		$replace = Inflector::pluralize(Inflector::underscore($className));
@@ -380,6 +391,8 @@ class Inflector extends Object {
  *
  * @param string $tableName Name of database table to get class name for
  * @return string
+ * @access public
+ * @static
  */
 	function classify($tableName) {
 		$replace = Inflector::camelize(Inflector::singularize($tableName));
@@ -390,6 +403,8 @@ class Inflector extends Object {
  *
  * @param string $string
  * @return string
+ * @access public
+ * @static
  */
 	function variable($string) {
 		$string = Inflector::camelize(Inflector::underscore($string));
@@ -400,10 +415,10 @@ class Inflector extends Object {
 }
 
 /**
- * Enter description here...
+ * Enclose a string for preg matching.
  *
- * @param unknown_type $string
- * @return unknown
+ * @param string $string String to enclose
+ * @return string Enclosed string
  */
 	function __enclose($string) {
 		return '(?:' . $string . ')';
diff --git a/cake/libs/l10n.php b/cake/libs/l10n.php
index 6bfc92c69..f1c02cf5c 100644
--- a/cake/libs/l10n.php
+++ b/cake/libs/l10n.php
@@ -329,9 +329,8 @@ class L10n extends Object {
  * If $language is null it attempt to get settings from I10n::__autoLanguage(); if this fails
  * the method will get the settings from I10n::__setLanguage();
  *
- * @param string $language
- * @return void
- * @access private
+ * @param string $language Language (if null will use DEFAULT_LANGUAGE if defined)
+ * @access public
  */
 	function get($language = null) {
 		if (!is_null($language)) {
@@ -344,7 +343,7 @@ class L10n extends Object {
  * Sets the class vars to correct values for $language.
  * If $language is null it will use the DEFAULT_LANGUAGE if defined
  *
- * @param string $language
+ * @param string $language Language (if null will use DEFAULT_LANGUAGE if defined)
  * @access private
  */
 	function __setLanguage($language = null) {
@@ -382,6 +381,8 @@ class L10n extends Object {
 	}
 /**
  * Attempts to find the locale settings based on the HTTP_ACCEPT_LANGUAGE variable
+ *
+ * @return boolean Success
  * @access private
  */
 	function __autoLanguage() {
diff --git a/cake/libs/neat_string.php b/cake/libs/neat_string.php
index ae8e4b86e..c06fea312 100644
--- a/cake/libs/neat_string.php
+++ b/cake/libs/neat_string.php
@@ -38,8 +38,10 @@ class NeatString{
 /**
  * Returns an array with each of the non-empty characters in $string as an element.
  *
- * @param string $string
- * @return array
+ * @param string $string String to split
+ * @return array An array where each element is a non empty character
+ * @access public
+ * @static
  */
 	function toArray($string) {
 		$split = preg_split('//', $string, -1, PREG_SPLIT_NO_EMPTY);
@@ -48,8 +50,10 @@ class NeatString{
 /**
  * Returns string with Cyrillic characters translated to Roman ones.
  *
- * @param string $string
- * @return string
+ * @param string $string String to translate
+ * @return string String with cyrillic chracters translated
+ * @access public
+ * @static
  */
 	function toRoman($string) {
 		$pl = array('ą','ć','ę','ł','ń','ó','ś','ź','ż','Ą','Ć','Ę','�?','Ń','Ó','Ś','Ź','Ż');
@@ -60,8 +64,10 @@ class NeatString{
 /**
  * Returns string as lowercase with whitespace removed.
  *
- * @param string $string
- * @return string
+ * @param string $string String to convert
+ * @return string Converted string
+ * @access public
+ * @static
  */
 	function toCompressed($string) {
 		$whitespace = array("\n", "	", "\r", "\0", "\x0B", " ");
@@ -74,6 +80,8 @@ class NeatString{
  * @param integer $length Length of generated password
  * @param string $available_chars List of characters to use in password
  * @return string Generated password
+ * @access public
+ * @static
  */
 	function randomPassword($length, $available_chars = 'ABDEFHKMNPRTWXYABDEFHKMNPRTWXY23456789') {
 		$chars = preg_split('//', $available_chars, -1, PREG_SPLIT_NO_EMPTY);
diff --git a/cake/libs/object.php b/cake/libs/object.php
index beccedd0f..75db8ad53 100644
--- a/cake/libs/object.php
+++ b/cake/libs/object.php
@@ -69,6 +69,7 @@ class Object {
  * Each class can override this method as necessary.
  *
  * @return string The name of this class
+ * @access public
  */
 	function toString() {
 		$class = get_class($this);
@@ -79,7 +80,8 @@ class Object {
  *
  * @param string $url  URL in the form of Cake URL ("/controller/method/parameter")
  * @param array $extra If array includes the key "return" it sets the AutoRender to true.
- * @return boolean  Success
+ * @return mixed  Success (true/false) or contents if 'return' is set in $extra
+ * @access public
  */
 	function requestAction($url, $extra = array()) {
 		if (!empty($url)) {
@@ -113,6 +115,7 @@ class Object {
  *
  * @param string $msg Log message
  * @param int $type Error type constant. Defined in app/config/core.php.
+ * @access public
  */
 	function log($msg, $type = LOG_ERROR) {
 		if (!class_exists('CakeLog')) {
@@ -138,10 +141,8 @@ class Object {
 /**
  * Allows setting of multiple properties of the object in a single line of code.
  *
- * @access public
- * @param array $properties An associative array containing
- *                          properties and corresponding values.
- * @return void
+ * @param array $properties An associative array containing properties and corresponding values.
+ * @access protected
  */
 	function _set($properties = array()) {
 		if (is_array($properties) && !empty($properties)) {
@@ -161,6 +162,7 @@ class Object {
  * @param string $method Method to be called in the error class (AppError or ErrorHandler classes)
  * @param array $messages Message that is to be displayed by the error class
  * @return error message
+ * @access public
  */
 	function cakeError($method, $messages) {
 		if (!class_exists('ErrorHandler')) {
@@ -184,9 +186,9 @@ class Object {
  * There are many uses for this method, see manual for examples
  *
  * @param string $name name of the class to persist
- * @return boolean
  * @param string $object the object to persist
- * @access public
+ * @return boolean Success
+ * @access protected
  * @todo add examples to manual
  */
 	function _persist($name, $return = null, &$object, $type = null) {
@@ -228,8 +230,8 @@ class Object {
  * Open the persistent class file for reading
  * Used by Object::_persist()
  *
- * @param string $name
- * @param string $type
+ * @param string $name Name of persisted class
+ * @param string $type Type of persistance (e.g: registry)
  * @access private
  */
 	function __openPersistent($name, $type = null) {