Doc Block changes

git-svn-id: https://phpexcel.svn.codeplex.com/svn/trunk@88400 2327b42d-5241-43d6-9e2a-de5ac946f064

Classes/PHPExcel/Calculation/Database.php

@@ -49,12 +49,14 @@ class PHPExcel_Calculation_Database {
 	/**
 	 * __fieldExtract
 	 *
+	 * Extracts the column ID to use for the data field.
+	 *
 	 * @access	private
 	 * @param	mixed[]		$database		The range of cells that makes up the list or database.
 	 *										A database is a list of related data in which rows of related
 	 *										information are records, and columns of data are fields. The
 	 *										first row of the list contains labels for each column.
-	 * @param	mixed[]		$field			Indicates which column is used in the function. Enter the
+	 * @param	mixed		$field			Indicates which column is used in the function. Enter the
 	 *										column label enclosed between double quotation marks, such as
 	 *										"Age" or "Yield," or a number (without quotation marks) that
 	 *										represents the position of the column within the list: 1 for
@@ -71,12 +73,15 @@ class PHPExcel_Calculation_Database {
 			return $keys[$field-1];
 		}
 		$key = array_search($field,$fieldNames);
-		return ($key) ? $key : null;
+		return ($key) ? $key : NULL;
 	}
 
 	/**
 	 * __filter
 	 *
+	 * Parses the selection criteria, extracts the database rows that match those criteria, and
+	 * returns that subset of rows.
+	 *
 	 * @access	private
 	 * @param	mixed[]		$database		The range of cells that makes up the list or database.
 	 *										A database is a list of related data in which rows of related
@@ -114,6 +119,7 @@ class PHPExcel_Calculation_Database {
 				$testConditionsCount++;
 			}
 		}
+
 		if ($testConditionsCount > 1) {
 			$testConditionSet = 'AND('.implode(',',$testConditions).')';
 		} elseif($testConditionsCount == 1) {
@@ -158,7 +164,7 @@ class PHPExcel_Calculation_Database {
 	 *										A database is a list of related data in which rows of related
 	 *										information are records, and columns of data are fields. The
 	 *										first row of the list contains labels for each column.
-	 * @param	mixed[]		$field			Indicates which column is used in the function. Enter the
+	 * @param	string|integer	$field		Indicates which column is used in the function. Enter the
 	 *										column label enclosed between double quotation marks, such as
 	 *										"Age" or "Yield," or a number (without quotation marks) that
 	 *										represents the position of the column within the list: 1 for
@@ -170,15 +176,12 @@ class PHPExcel_Calculation_Database {
 	 *										column.
 	 * @return	float
 	 *
-	 * @TODO	Numeric value in $field to reference a column position rather than a name.
-	 *
 	 */
 	public static function DAVERAGE($database,$field,$criteria) {
 		$field = self::__fieldExtract($database,$field);
 		if (is_null($field)) {
 			return NULL;
 		}
-
 		//	reduce the database to a set of rows that match all the criteria
 		$database = self::__filter($database,$criteria);
 		//	extract an array of values for the requested column
@@ -201,13 +204,16 @@ class PHPExcel_Calculation_Database {
 	 * Excel Function:
 	 *		DCOUNT(database,[field],criteria)
 	 *
+	 * Excel Function:
+	 *		DAVERAGE(database,field,criteria)
+	 *
 	 * @access	public
 	 * @category Database Functions
 	 * @param	mixed[]			$database	The range of cells that makes up the list or database.
 	 *										A database is a list of related data in which rows of related
 	 *										information are records, and columns of data are fields. The
 	 *										first row of the list contains labels for each column.
-	 * @param	mixed[]		$field			Indicates which column is used in the function. Enter the
+	 * @param	string|integer	$field		Indicates which column is used in the function. Enter the
 	 *										column label enclosed between double quotation marks, such as
 	 *										"Age" or "Yield," or a number (without quotation marks) that
 	 *										represents the position of the column within the list: 1 for
@@ -222,8 +228,6 @@ class PHPExcel_Calculation_Database {
 	 * @TODO	The field argument is optional. If field is omitted, DCOUNT counts all records in the
 	 *			database that match the criteria.
 	 *
-	 * @TODO	Numeric value in $field to reference a column position rather than a name.
-	 *
 	 */
 	public static function DCOUNT($database,$field,$criteria) {
 		$field = self::__fieldExtract($database,$field);
@@ -270,11 +274,9 @@ class PHPExcel_Calculation_Database {
 	 *										column.
 	 * @return	integer
 	 *
-	 * @TODO	The field argument is optional. If field is omitted, DCOUNT counts all records in the
+	 * @TODO	The field argument is optional. If field is omitted, DCOUNTA counts all records in the
 	 *			database that match the criteria.
 	 *
-	 * @TODO	Numeric value in $field to reference a column position rather than a name.
-	 *
 	 */
 	public static function DCOUNTA($database,$field,$criteria) {
 		$field = self::__fieldExtract($database,$field);

Classes/PHPExcel/Calculation/DateTime.php

@@ -240,7 +240,7 @@ class PHPExcel_Calculation_DateTime {
 	 *
 	 * @access	public
 	 * @category Date/Time Functions
-	 * @param	int|mixed[]		$year	The value of the year argument can include one to four digits.
+	 * @param	integer		$year	The value of the year argument can include one to four digits.
 	 *								Excel interprets the year argument according to the configured
 	 *								date system: 1900 or 1904.
 	 *								If year is between 0 (zero) and 1899 (inclusive), Excel adds that
@@ -251,7 +251,7 @@ class PHPExcel_Calculation_DateTime {
 	 *								2008.
 	 *								If year is less than 0 or is 10000 or greater, Excel returns the
 	 *								#NUM! error value.
-	 * @param	int|mixed[]		$month	A positive or negative integer representing the month of the year
+	 * @param	integer		$month	A positive or negative integer representing the month of the year
 	 *								from 1 to 12 (January to December).
 	 *								If month is greater than 12, month adds that number of months to
 	 *								the first month in the year specified. For example, DATE(2008,14,2)
@@ -260,7 +260,7 @@ class PHPExcel_Calculation_DateTime {
 	 *								number of months, plus 1, from the first month in the year
 	 *								specified. For example, DATE(2008,-3,2) returns the serial number
 	 *								representing September 2, 2007.
-	 * @param	int|mixed[]		$day	A positive or negative integer representing the day of the month
+	 * @param	integer		$day	A positive or negative integer representing the day of the month
 	 *								from 1 to 31.
 	 *								If day is greater than the number of days in the month specified,
 	 *								day adds that number of days to the first day in the month. For
@@ -345,14 +345,14 @@ class PHPExcel_Calculation_DateTime {
 	 *
 	 * @access	public
 	 * @category Date/Time Functions
-	 * @param	int|mixed[]		$hour		A number from 0 (zero) to 32767 representing the hour.
+	 * @param	integer		$hour		A number from 0 (zero) to 32767 representing the hour.
 	 *									Any value greater than 23 will be divided by 24 and the remainder
 	 *									will be treated as the hour value. For example, TIME(27,0,0) =
 	 *									TIME(3,0,0) = .125 or 3:00 AM.
-	 * @param	int|mixed[]		$minute		A number from 0 to 32767 representing the minute.
+	 * @param	integer		$minute		A number from 0 to 32767 representing the minute.
 	 *									Any value greater than 59 will be converted to hours and minutes.
 	 *									For example, TIME(0,750,0) = TIME(12,30,0) = .520833 or 12:30 PM.
-	 * @param	int|mixed[]		$second		A number from 0 to 32767 representing the second.
+	 * @param	integer		$second		A number from 0 to 32767 representing the second.
 	 *									Any value greater than 59 will be converted to hours, minutes,
 	 *									and seconds. For example, TIME(0,0,2000) = TIME(0,33,22) = .023148
 	 *									or 12:33:20 AM

Classes/PHPExcel/Calculation/Financial.php

@@ -181,7 +181,7 @@ class PHPExcel_Calculation_Financial {
 	 * @param	float	$rate			The security's annual coupon rate.
 	 * @param	float	$par			The security's par value.
 	 *									If you omit par, ACCRINT uses $1,000.
-	 * @param	float	$frequency		the number of coupon payments per year.
+	 * @param	integer	$frequency		the number of coupon payments per year.
 	 *									Valid frequency values are:
 	 *										1	Annual
 	 *										2	Semi-Annual
@@ -190,7 +190,7 @@ class PHPExcel_Calculation_Financial {
 	 *									also available
 	 *										6	Bimonthly
 	 *										12	Monthly
-	 * @param	int		$basis			The type of day count to use.
+	 * @param	integer	$basis			The type of day count to use.
 	 *										0 or omitted	US (NASD) 30/360
 	 *										1				Actual/actual
 	 *										2				Actual/360
@@ -240,7 +240,7 @@ class PHPExcel_Calculation_Financial {
 	 * @param	float	rate		The security's annual coupon rate.
 	 * @param	float	par			The security's par value.
 	 *									If you omit par, ACCRINT uses $1,000.
-	 * @param	int		basis		The type of day count to use.
+	 * @param	integer	basis		The type of day count to use.
 	 *										0 or omitted	US (NASD) 30/360
 	 *										1				Actual/actual
 	 *										2				Actual/360
@@ -271,6 +271,37 @@ class PHPExcel_Calculation_Financial {
 	}	//	function ACCRINTM()
 
 
+	/**
+	 * AMORDEGRC
+	 *
+	 * Returns the depreciation for each accounting period.
+	 * This function is provided for the French accounting system. If an asset is purchased in
+	 * the middle of the accounting period, the prorated depreciation is taken into account.
+	 * The function is similar to AMORLINC, except that a depreciation coefficient is applied in
+	 * the calculation depending on the life of the assets.
+	 * This function will return the depreciation until the last period of the life of the assets
+	 * or until the cumulated value of depreciation is greater than the cost of the assets minus
+	 * the salvage value.
+	 *
+	 * Excel Function:
+	 *		AMORDEGRC(cost,purchased,firstPeriod,salvage,period,rate[,basis])
+	 *
+	 * @access	public
+	 * @category Financial Functions
+	 * @param	float	cost		The cost of the asset.
+	 * @param	mixed	purchased	Date of the purchase of the asset.
+	 * @param	mixed	firstPeriod	Date of the end of the first period.
+	 * @param	mixed	salvage		The salvage value at the end of the life of the asset.
+	 * @param	float	period		The period.
+	 * @param	float	rate		Rate of depreciation.
+	 * @param	int		basis		The type of day count to use.
+	 *										0 or omitted	US (NASD) 30/360
+	 *										1				Actual/actual
+	 *										2				Actual/360
+	 *										3				Actual/365
+	 *										4				European 30/360
+	 * @return	float
+	 */
 	public static function AMORDEGRC($cost, $purchased, $firstPeriod, $salvage, $period, $rate, $basis=0) {
 		$cost			= PHPExcel_Calculation_Functions::flattenSingleValue($cost);
 		$purchased		= PHPExcel_Calculation_Functions::flattenSingleValue($purchased);
@@ -280,8 +311,13 @@ class PHPExcel_Calculation_Financial {
 		$rate			= PHPExcel_Calculation_Functions::flattenSingleValue($rate);
 		$basis			= (is_null($basis))	? 0 :	(int) PHPExcel_Calculation_Functions::flattenSingleValue($basis);
 
+		//	The depreciation coefficients are:
+		//	Life of assets (1/rate)		Depreciation coefficient
+		//	Less than 3 years			1
+		//	Between 3 and 4 years		1.5
+		//	Between 5 and 6 years		2
+		//	More than 6 years			2.5
 		$fUsePer = 1.0 / $rate;
-
 		if ($fUsePer < 3.0) {
 			$amortiseCoeff = 1.0;
 		} elseif ($fUsePer < 5.0) {
@@ -316,6 +352,32 @@ class PHPExcel_Calculation_Financial {
 	}	//	function AMORDEGRC()
 
 
+	/**
+	 * AMORLINC
+	 *
+	 * Returns the depreciation for each accounting period.
+	 * This function is provided for the French accounting system. If an asset is purchased in
+	 * the middle of the accounting period, the prorated depreciation is taken into account.
+	 *
+	 * Excel Function:
+	 *		AMORLINC(cost,purchased,firstPeriod,salvage,period,rate[,basis])
+	 *
+	 * @access	public
+	 * @category Financial Functions
+	 * @param	float	cost		The cost of the asset.
+	 * @param	mixed	purchased	Date of the purchase of the asset.
+	 * @param	mixed	firstPeriod	Date of the end of the first period.
+	 * @param	mixed	salvage		The salvage value at the end of the life of the asset.
+	 * @param	float	period		The period.
+	 * @param	float	rate		Rate of depreciation.
+	 * @param	int		basis		The type of day count to use.
+	 *										0 or omitted	US (NASD) 30/360
+	 *										1				Actual/actual
+	 *										2				Actual/360
+	 *										3				Actual/365
+	 *										4				European 30/360
+	 * @return	float
+	 */
 	public static function AMORLINC($cost, $purchased, $firstPeriod, $salvage, $period, $rate, $basis=0) {
 		$cost			= PHPExcel_Calculation_Functions::flattenSingleValue($cost);
 		$purchased		= PHPExcel_Calculation_Functions::flattenSingleValue($purchased);