Doc Block changes

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

Classes/PHPExcel/Calculation/Statistical.php

@@ -141,6 +141,7 @@ class PHPExcel_Calculation_Statistical {
 
 	/**
 	 * The natural logarithm of the beta function.
+	 *
 	 * @param p require p>0
 	 * @param q require q>0
 	 * @return 0 if p<=0, q<=0 or p+q>2.55E305 to avoid errors and over/underflow

Classes/PHPExcel/Chart/DataSeriesValues.php

@@ -201,7 +201,7 @@ class PHPExcel_Chart_DataSeriesValues
 	}
 
 	/**
-	 *	Identify if the Data Series is a multi-level or a simple series
+	 * Return the level count of a multi-level Data Series
 	 *
 	 * @return	boolean
 	 */

Classes/PHPExcel/Reader/OOCalc.php

@@ -93,7 +93,6 @@ class PHPExcel_Reader_OOCalc implements PHPExcel_Reader_IReader
 	 *		Set to false (the default) to advise the Reader to read both data and formatting for cells.
 	 *
 	 * @param	boolean	$pValue
-	 *
 	 * @return	PHPExcel_Reader_OOCalc
 	 */
 	public function setReadDataOnly($pValue = false) {

Classes/PHPExcel/Worksheet.php

@@ -535,11 +535,24 @@ class PHPExcel_Worksheet implements PHPExcel_IComparable
 		return $pChart;
 	}
 
+	/**
+	 * Return the count of charts on this worksheet
+	 *
+	 * @return int		The number of charts
+	 * @throws Exception
+	 */
 	public function getChartCount()
 	{
 		return count($this->_chartCollection);
 	}
 
+	/**
+	 * Get a chart by its index position
+	 *
+	 * @param	string	$index			Chart index position
+	 * @return	false|PHPExcel_Chart
+	 * @throws Exception
+	 */
 	public function getChartByIndex($index = null)
 	{
 		$chartCount = count($this->_chartCollection);
@@ -556,6 +569,12 @@ class PHPExcel_Worksheet implements PHPExcel_IComparable
 		return $this->_chartCollection[$index];
 	}
 
+	/**
+	 * Return an array of the names of charts on this worksheet
+	 *
+	 * @return string[]		The names of charts
+	 * @throws Exception
+	 */
 	public function getChartNames()
 	{
 		$chartNames = array();
@@ -565,6 +584,13 @@ class PHPExcel_Worksheet implements PHPExcel_IComparable
 		return $chartNames;
 	}
 
+	/**
+	 * Get a chart by name
+	 *
+	 * @param	string	$chartName		Chart name
+	 * @return	false|PHPExcel_Chart
+	 * @throws Exception
+	 */
 	public function getChartByName($chartName = '')
 	{
 		$chartCount = count($this->_chartCollection);
@@ -1250,7 +1276,6 @@ class PHPExcel_Worksheet implements PHPExcel_IComparable
 	 * Get column dimension at a specific column by using numeric cell coordinates
 	 *
 	 * @param	string $pColumn		Numeric column coordinate of the cell
-	 * @param	string $pRow		Numeric row coordinate of the cell
 	 * @return	PHPExcel_Worksheet_ColumnDimension
 	 */
 	public function getColumnDimensionByColumn($pColumn = 0)
@@ -1284,7 +1309,7 @@ class PHPExcel_Worksheet implements PHPExcel_IComparable
 	 * Set default style - should only be used by PHPExcel_IReader implementations!
 	 *
 	 * @deprecated
-	 * @param	PHPExcel_Style $value
+	 * @param	PHPExcel_Style	$pValue
 	 * @throws	Exception
 	 * @return PHPExcel_Worksheet
 	 */
@@ -2221,7 +2246,7 @@ class PHPExcel_Worksheet implements PHPExcel_IComparable
 	/**
 	 * Selected cell
 	 *
-	 * @param	string		$pCell		Cell (i.e. A1)
+	 * @param	string		$pCoordinate	Cell (i.e. A1)
 	 * @return PHPExcel_Worksheet
 	 */
 	public function setSelectedCell($pCoordinate = 'A1')
@@ -2588,7 +2613,7 @@ class PHPExcel_Worksheet implements PHPExcel_IComparable
 	/**
 	 * Hyperlink at a specific coordinate exists?
 	 *
-	 * @param string $pCellCoordinate
+	 * @param string $pCoordinate
 	 * @return boolean
 	 */
 	public function hyperlinkExists($pCoordinate = 'A1')
@@ -2643,7 +2668,7 @@ class PHPExcel_Worksheet implements PHPExcel_IComparable
 	/**
 	 * Data validation at a specific coordinate exists?
 	 *
-	 * @param string $pCellCoordinate
+	 * @param string $pCoordinate
 	 * @return boolean
 	 */
 	public function dataValidationExists($pCoordinate = 'A1')

Classes/PHPExcel/Worksheet/CellIterator.php

@@ -117,7 +117,7 @@ class PHPExcel_Worksheet_CellIterator implements Iterator
     }
 
     /**
-     * More PHPExcel_Cell instances available?
+     * Are there any more PHPExcel_Cell instances available?
      *
      * @return boolean
      */
@@ -151,9 +151,9 @@ class PHPExcel_Worksheet_CellIterator implements Iterator
     }
 
 	/**
-	 * Set loop only existing cells
+	 * Set the iterator to loop only existing cells
 	 *
-	 * @return boolean
+	 * @param	boolean		$value
 	 */
     public function setIterateOnlyExistingCells($value = true) {
     	$this->_onlyExistingCells = $value;

Classes/PHPExcel/Worksheet/PageSetup.php

@@ -214,7 +214,7 @@ class PHPExcel_Worksheet_PageSetup
 	  *
 	  * @var boolean
 	  */
-	private $_fitToPage		= false;
+	private $_fitToPage		= FALSE;
 
 	/**
 	  * Fit To Height
@@ -251,28 +251,28 @@ class PHPExcel_Worksheet_PageSetup
 	 *
 	 * @var boolean
 	 */
-	private $_horizontalCentered = false;
+	private $_horizontalCentered = FALSE;
 
 	/**
 	 * Center page vertically
 	 *
 	 * @var boolean
 	 */
-	private $_verticalCentered = false;
+	private $_verticalCentered = FALSE;
 
 	/**
 	 * Print area
 	 *
 	 * @var string
 	 */
-	private $_printArea = null;
+	private $_printArea = NULL;
 
 	/**
 	 * First page number
 	 *
 	 * @var int
 	 */
-	private $_firstPageNumber = null;
+	private $_firstPageNumber = NULL;
 
     /**
      * Create a new PHPExcel_Worksheet_PageSetup
@@ -338,8 +338,8 @@ class PHPExcel_Worksheet_PageSetup
 	 *
 	 * @param 	int?	$pValue
 	 * @param boolean	$pUpdate	Update fitToPage so scaling applies rather than fitToHeight / fitToWidth
-	 * @throws 	Exception
 	 * @return PHPExcel_Worksheet_PageSetup
+	 * @throws 	Exception
 	 */
 	public function setScale($pValue = 100, $pUpdate = true) {
 		// Microsoft Office Excel 2007 only allows setting a scale between 10 and 400 via the user interface,
@@ -370,7 +370,7 @@ class PHPExcel_Worksheet_PageSetup
 	 * @param boolean $pValue
 	 * @return PHPExcel_Worksheet_PageSetup
 	 */
-	public function setFitToPage($pValue = true) {
+	public function setFitToPage($pValue = TRUE) {
 		$this->_fitToPage = $pValue;
 		return $this;
 	}
@@ -391,10 +391,10 @@ class PHPExcel_Worksheet_PageSetup
 	 * @param boolean $pUpdate Update fitToPage so it applies rather than scaling
 	 * @return PHPExcel_Worksheet_PageSetup
 	 */
-	public function setFitToHeight($pValue = 1, $pUpdate = true) {
+	public function setFitToHeight($pValue = 1, $pUpdate = TRUE) {
 		$this->_fitToHeight = $pValue;
 		if ($pUpdate) {
-			$this->_fitToPage = true;
+			$this->_fitToPage = TRUE;
 		}
 		return $this;
 	}
@@ -415,10 +415,10 @@ class PHPExcel_Worksheet_PageSetup
 	 * @param boolean $pUpdate Update fitToPage so it applies rather than scaling
 	 * @return PHPExcel_Worksheet_PageSetup
 	 */
-	public function setFitToWidth($pValue = 1, $pUpdate = true) {
+	public function setFitToWidth($pValue = 1, $pUpdate = TRUE) {
 		$this->_fitToWidth = $pValue;
 		if ($pUpdate) {
-			$this->_fitToPage = true;
+			$this->_fitToPage = TRUE;
 		}
 		return $this;
 	}
@@ -639,8 +639,8 @@ class PHPExcel_Worksheet_PageSetup
 	 * @param	string	$method	Determines the method used when setting multiple print areas
 	 *							Default behaviour, or the "O" method, overwrites existing print area
 	 *							The "I" method, inserts the new print area before any specified index, or at the end of the list
-	 *	@throws	Exception
 	 * @return	PHPExcel_Worksheet_PageSetup
+	 * @throws	Exception
 	 */
 	public function setPrintArea($value, $index = 0, $method = self::SETPRINTRANGE_OVERWRITE) {
 		if (strpos($value,'!') !== false) {
@@ -697,8 +697,8 @@ class PHPExcel_Worksheet_PageSetup
 	 *								Specifying an index value of 0, will always append the new print range at the end of the
 	 *								list.
 	 *							Print areas are numbered from 1
-	 *	@throws	Exception
 	 * @return	PHPExcel_Worksheet_PageSetup
+	 * @throws	Exception
 	 */
 	public function addPrintArea($value, $index = -1) {
 		return $this->setPrintArea($value, $index, self::SETPRINTRANGE_INSERT);
@@ -724,8 +724,8 @@ class PHPExcel_Worksheet_PageSetup
 	 * @param	string	$method		Determines the method used when setting multiple print areas
 	 *								Default behaviour, or the "O" method, overwrites existing print area
 	 *								The "I" method, inserts the new print area before any specified index, or at the end of the list
-	 *	@throws	Exception
 	 * @return	PHPExcel_Worksheet_PageSetup
+	 * @throws	Exception
 	 */
     public function setPrintAreaByColumnAndRow($column1, $row1, $column2, $row2, $index = 0, $method = self::SETPRINTRANGE_OVERWRITE)
     {
@@ -735,18 +735,18 @@ class PHPExcel_Worksheet_PageSetup
 	/**
 	 * Add a new print area to the list of print areas
 	 *
-	 *	@param	int		$column1	Column 1
+	 * @param	int		$column1	Start Column for the print area
-	 *	@param	int		$row1		Row 1
+	 * @param	int		$row1		Start Row for the print area
-	 *	@param	int		$column2	Column 2
+	 * @param	int		$column2	End Column for the print area
-	 *	@param	int		$row2		Row 2
+	 * @param	int		$row2		End Row for the print area
 	 * @param	int		$index		Identifier for a specific print area range allowing several ranges to be set
 	 *								A positive index will insert after that indexed entry in the print areas list, while a
 	 *									negative index will insert before the indexed entry.
 	 *									Specifying an index value of 0, will always append the new print range at the end of the
 	 *									list.
 	 *								Print areas are numbered from 1
-	 *	@throws	Exception
 	 * @return	PHPExcel_Worksheet_PageSetup
+	 * @throws	Exception
 	 */
     public function addPrintAreaByColumnAndRow($column1, $row1, $column2, $row2, $index = -1)
     {

Classes/PHPExcel/Writer/Excel2007/Chart.php

@@ -108,6 +108,13 @@ class PHPExcel_Writer_Excel2007_Chart extends PHPExcel_Writer_Excel2007_WriterPa
 		return $objWriter->getData();
 	}
 
+	/**
+	 * Write Chart Title
+	 *
+	 * @param	PHPExcel_Chart_Title		$title
+	 * @param 	PHPExcel_Shared_XMLWriter 	$objWriter 		XML Writer
+	 * @throws 	Exception
+	 */
 	private function _writeTitle(PHPExcel_Chart_Title $title = null, $objWriter)
 	{
 		if (is_null($title)) {
@@ -145,6 +152,13 @@ class PHPExcel_Writer_Excel2007_Chart extends PHPExcel_Writer_Excel2007_WriterPa
 		$objWriter->endElement();
 	}
 
+	/**
+	 * Write Chart Legend
+	 *
+	 * @param	PHPExcel_Chart_Legend		$legend
+	 * @param 	PHPExcel_Shared_XMLWriter 	$objWriter 		XML Writer
+	 * @throws 	Exception
+	 */
 	private function _writeLegend(PHPExcel_Chart_Legend $legend = null, $objWriter)
 	{
 		if (is_null($legend)) {
@@ -189,6 +203,15 @@ class PHPExcel_Writer_Excel2007_Chart extends PHPExcel_Writer_Excel2007_WriterPa
 		$objWriter->endElement();
 	}
 
+	/**
+	 * Write Chart Plot Area
+	 *
+	 * @param	PHPExcel_Chart_PlotArea		$plotArea
+	 * @param	PHPExcel_Chart_Title		$xAxisLabel
+	 * @param	PHPExcel_Chart_Title		$yAxisLabel
+	 * @param 	PHPExcel_Shared_XMLWriter 	$objWriter 		XML Writer
+	 * @throws 	Exception
+	 */
 	private function _writePlotArea(PHPExcel_Chart_PlotArea $plotArea,
 									PHPExcel_Chart_Title $xAxisLabel = NULL,
 									PHPExcel_Chart_Title $yAxisLabel = NULL,
@@ -318,6 +341,12 @@ class PHPExcel_Writer_Excel2007_Chart extends PHPExcel_Writer_Excel2007_WriterPa
 		$objWriter->endElement();
 	}
 
+	/**
+	 * Write Data Labels
+	 *
+	 * @param 	PHPExcel_Shared_XMLWriter 	$objWriter 		XML Writer
+	 * @throws 	Exception
+	 */
 	private function _writeDataLbls($objWriter)
 	{
 		$objWriter->startElement('c:dLbls');
@@ -353,6 +382,18 @@ class PHPExcel_Writer_Excel2007_Chart extends PHPExcel_Writer_Excel2007_WriterPa
 		$objWriter->endElement();
 	}
 
+	/**
+	 * Write Category Axis
+	 *
+	 * @param 	PHPExcel_Shared_XMLWriter 	$objWriter 		XML Writer
+	 * @param 	PHPExcel_Chart_PlotArea		$plotArea
+	 * @param 	PHPExcel_Chart_Title		$xAxisLabel
+	 * @param 	string						$groupType		Chart type
+	 * @param 	string						$id1
+	 * @param 	string						$id2
+	 * @param 	boolean						$isMultiLevelSeries
+	 * @throws 	Exception
+	 */
 	private function _writeCatAx($objWriter, PHPExcel_Chart_PlotArea $plotArea, $xAxisLabel, $groupType, $id1, $id2, $isMultiLevelSeries)
 	{
 		$objWriter->startElement('c:catAx');
@@ -464,6 +505,18 @@ class PHPExcel_Writer_Excel2007_Chart extends PHPExcel_Writer_Excel2007_WriterPa
 	}
 
 
+	/**
+	 * Write Value Axis
+	 *
+	 * @param 	PHPExcel_Shared_XMLWriter 	$objWriter 		XML Writer
+	 * @param 	PHPExcel_Chart_PlotArea		$plotArea
+	 * @param 	PHPExcel_Chart_Title		$yAxisLabel
+	 * @param 	string						$groupType		Chart type
+	 * @param 	string						$id1
+	 * @param 	string						$id2
+	 * @param 	boolean						$isMultiLevelSeries
+	 * @throws 	Exception
+	 */
 	private function _writeValAx($objWriter, PHPExcel_Chart_PlotArea $plotArea, $yAxisLabel, $groupType, $id1, $id2, $isMultiLevelSeries)
 	{
 		$objWriter->startElement('c:valAx');
@@ -573,6 +626,13 @@ class PHPExcel_Writer_Excel2007_Chart extends PHPExcel_Writer_Excel2007_WriterPa
 	}
 
 
+	/**
+	 * Get the data series type(s) for a chart plot series
+	 *
+	 * @param 	PHPExcel_Chart_PlotArea		$plotArea
+	 * @return	string|array
+	 * @throws 	Exception
+	 */
 	private static function _getChartType($plotArea)
 	{
 		$groupCount = $plotArea->getPlotGroupCount();
@@ -593,6 +653,17 @@ class PHPExcel_Writer_Excel2007_Chart extends PHPExcel_Writer_Excel2007_WriterPa
 		return $chartType;
 	}
 
+	/**
+	 * Write Plot Group (series of related plots)
+	 *
+	 * @param	PHPExcel_Chart_DataSeries		$plotGroup
+	 * @param	string							$groupType				Type of plot for dataseries
+	 * @param 	PHPExcel_Shared_XMLWriter 		$objWriter 				XML Writer
+	 * @param	boolean							&$catIsMultiLevelSeries	Is category a multi-series category
+	 * @param	boolean							&$valIsMultiLevelSeries	Is value set a multi-series set
+	 * @param	string							&$plotGroupingType		Type of grouping for multi-series values
+	 * @throws 	Exception
+	 */
 	private function _writePlotGroup($plotGroup, $groupType, $objWriter, &$catIsMultiLevelSeries, &$valIsMultiLevelSeries, &$plotGroupingType)
 	{
 		if (is_null($plotGroup)) {
@@ -770,6 +841,13 @@ class PHPExcel_Writer_Excel2007_Chart extends PHPExcel_Writer_Excel2007_WriterPa
 		}
 	}
 
+	/**
+	 * Write Plot Series Label
+	 *
+	 * @param	PHPExcel_Chart_DataSeriesValues		$plotSeriesLabel
+	 * @param 	PHPExcel_Shared_XMLWriter 			$objWriter 			XML Writer
+	 * @throws 	Exception
+	 */
 	private function _writePlotSeriesLabel($plotSeriesLabel, $objWriter)
 	{
 		if (is_null($plotSeriesLabel)) {
@@ -798,6 +876,15 @@ class PHPExcel_Writer_Excel2007_Chart extends PHPExcel_Writer_Excel2007_WriterPa
 
 	}
 
+	/**
+	 * Write Plot Series Values
+	 *
+	 * @param	PHPExcel_Chart_DataSeriesValues		$plotSeriesValues
+	 * @param 	PHPExcel_Shared_XMLWriter 			$objWriter 			XML Writer
+	 * @param	string								$groupType			Type of plot for dataseries
+	 * @param	string								$dataType			Datatype of series values
+	 * @throws 	Exception
+	 */
 	private function _writePlotSeriesValues($plotSeriesValues, $objWriter, $groupType, $dataType='str')
 	{
 		if (is_null($plotSeriesValues)) {
@@ -878,6 +965,13 @@ class PHPExcel_Writer_Excel2007_Chart extends PHPExcel_Writer_Excel2007_WriterPa
 		}
 	}
 
+	/**
+	 * Write Bubble Chart Details
+	 *
+	 * @param	PHPExcel_Chart_DataSeriesValues		$plotSeriesValues
+	 * @param 	PHPExcel_Shared_XMLWriter 			$objWriter 			XML Writer
+	 * @throws 	Exception
+	 */
 	private function _writeBubbles($plotSeriesValues, $objWriter)
 	{
 		if (is_null($plotSeriesValues)) {
@@ -912,6 +1006,13 @@ class PHPExcel_Writer_Excel2007_Chart extends PHPExcel_Writer_Excel2007_WriterPa
 		$objWriter->endElement();
 	}
 
+	/**
+	 * Write Layout
+	 *
+	 * @param	PHPExcel_Chart_Layout		$layout
+	 * @param 	PHPExcel_Shared_XMLWriter 	$objWriter 		XML Writer
+	 * @throws 	Exception
+	 */
 	private function _writeLayout(PHPExcel_Chart_Layout $layout = NULL, $objWriter)
 	{
 		$objWriter->startElement('c:layout');
@@ -974,6 +1075,12 @@ class PHPExcel_Writer_Excel2007_Chart extends PHPExcel_Writer_Excel2007_WriterPa
 		$objWriter->endElement();
 	}
 
+	/**
+	 * Write Alternate Content block
+	 *
+	 * @param 	PHPExcel_Shared_XMLWriter 	$objWriter 		XML Writer
+	 * @throws 	Exception
+	 */
 	private function _writeAlternateContent($objWriter)
 	{
 		$objWriter->startElement('mc:AlternateContent');
@@ -997,6 +1104,12 @@ class PHPExcel_Writer_Excel2007_Chart extends PHPExcel_Writer_Excel2007_WriterPa
 		$objWriter->endElement();
 	}
 
+	/**
+	 * Write Printer Settings
+	 *
+	 * @param 	PHPExcel_Shared_XMLWriter 	$objWriter 		XML Writer
+	 * @throws 	Exception
+	 */
 	private function _writePrintSettings($objWriter)
 	{
 		$objWriter->startElement('c:printSettings');

Classes/PHPExcel/Writer/Excel2007/ContentTypes.php

@@ -39,6 +39,7 @@ class PHPExcel_Writer_Excel2007_ContentTypes extends PHPExcel_Writer_Excel2007_W
 	 * Write content types to XML format
 	 *
 	 * @param 	PHPExcel	$pPHPExcel
+	 * @param	boolean		$includeCharts	Flag indicating if we should include drawing details for charts
 	 * @return 	string 						XML Output
 	 * @throws 	Exception
 	 */

Classes/PHPExcel/Writer/Excel2007/Drawing.php

@@ -39,6 +39,8 @@ class PHPExcel_Writer_Excel2007_Drawing extends PHPExcel_Writer_Excel2007_Writer
 	 * Write drawings to XML format
 	 *
 	 * @param 	PHPExcel_Worksheet	$pWorksheet
+	 * @param	int					&$chartRef		Chart ID
+	 * @param	boolean				$includeCharts	Flag indicating if we should include drawing details for charts
 	 * @return 	string 				XML Output
 	 * @throws 	Exception
 	 */