From ab0e0c2a0d515b110d1837b4b025236fd9ffce20 Mon Sep 17 00:00:00 2001 From: Jesse Donat Date: Wed, 17 Oct 2018 17:00:58 -0500 Subject: [PATCH] Documentation improvments --- README.md | 39 ++++++++++++++++++++++++++++----------- src/DataExport.php | 6 ++++-- src/DataSheet.php | 35 +++++++++++++++++++++++------------ src/EngineInterface.php | 3 ++- src/Engines/CsvEngine.php | 2 ++ 5 files changed, 59 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index ccbe48e..bcdb648 100644 --- a/README.md +++ b/README.md @@ -44,9 +44,11 @@ composer require 'quorum/exporter' function __construct($engine) ``` +DataExport is the object used to orchestrate the export process regardless of export format. + ##### Parameters: -- ***\Quorum\Exporter\EngineInterface*** `$engine` +- ***\Quorum\Exporter\EngineInterface*** `$engine` - The engine by which to export the data sheets. --- @@ -61,7 +63,7 @@ Add a Data Sheet to the export. ##### Parameters: - ***\Quorum\Exporter\DataSheet*** `$sheet` - The DataSheet to add to the export -- ***null*** | ***string*** `$sheetTitle` - Optional Title to give the data export. +- ***string*** | ***null*** `$sheetTitle` - Optional Title to give the data export. Most Engines will interpret this as filename (sans file extension). If excluded, the name will be left to the engine. @@ -82,9 +84,18 @@ NULL will open a php://output resource. ### Class: \Quorum\Exporter\DataSheet +#### Method: DataSheet->__construct +```php +function __construct([ $name = null]) +``` -#### Undocumented Method: `DataSheet->__construct([ $name = null])` +DataSheet is the representation of a Worksheet + +##### Parameters: + +- ***string*** | ***null*** `$name` - The name to give the sheet. The use is Engine implementation specific but is likely + filename or Sheet name --- @@ -96,31 +107,35 @@ function getName() ##### Returns: -- ***string*** +- ***string*** | ***null*** --- -#### Method: DataSheet->addRows +#### Method: DataSheet->addRow ```php -function addRows($dataSet) +function addRow($row) ``` +Append a row worth of data to the end of the Worksheet. + ##### Parameters: -- ***array*** | ***\Iterator*** `$dataSet` +- ***array*** `$row` - An array of scalars. Otherwise an InvalidDataTypeException will be thrown. --- -#### Method: DataSheet->addRow +#### Method: DataSheet->addRows ```php -function addRow($row) +function addRows($dataSet) ``` +Append multiple rows of data to the end of the Worksheet. + ##### Parameters: -- ***array*** `$row` +- ***array*** | ***\Iterator*** `$dataSet` - An iterable of arrays of scalars. --- @@ -172,7 +187,7 @@ Checks if current position is valid ##### Returns: -- ***boolean*** +- ***bool*** --- @@ -331,6 +346,8 @@ function getEnclosure() function disableBom([ $disable = true]) ``` +Whether to disable the leading Byte Order Mark for the given encoding from being output. + ##### Parameters: - ***bool*** `$disable` diff --git a/src/DataExport.php b/src/DataExport.php index 60274ea..cd38c3b 100644 --- a/src/DataExport.php +++ b/src/DataExport.php @@ -17,7 +17,9 @@ class DataExport { protected $engine; /** - * @param EngineInterface $engine + * DataExport is the object used to orchestrate the export process regardless of export format. + * + * @param \Quorum\Exporter\EngineInterface $engine The engine by which to export the data sheets. */ public function __construct( EngineInterface $engine ) { $this->engine = $engine; @@ -27,7 +29,7 @@ public function __construct( EngineInterface $engine ) { * Add a Data Sheet to the export. * * @param DataSheet $sheet The DataSheet to add to the export - * @param null|string $sheetTitle Optional Title to give the data export. + * @param string|null $sheetTitle Optional Title to give the data export. * Most Engines will interpret this as filename (sans file extension). * If excluded, the name will be left to the engine. */ diff --git a/src/DataSheet.php b/src/DataSheet.php index 249a54a..5b3ce43 100644 --- a/src/DataSheet.php +++ b/src/DataSheet.php @@ -28,29 +28,29 @@ class DataSheet implements \Iterator { */ protected $currentValue = null; + /** + * DataSheet is the representation of a Worksheet + * + * @param string|null $name The name to give the sheet. The use is Engine implementation specific but is likely + * filename or Sheet name + */ public function __construct( $name = null ) { $this->name = $name; $this->tmpStream = fopen("php://temp", "r+"); } /** - * @return string + * @return string|null */ public function getName() { return $this->name; } /** - * @param array|\Iterator $dataSet - */ - public function addRows( $dataSet ) { - foreach( $dataSet as $row ) { - $this->addRow($row); - } - } - - /** - * @param array $row + * Append a row worth of data to the end of the Worksheet. + * + * @param array $row An array of scalars. Otherwise an InvalidDataTypeException will be thrown. + * @throws InvalidDataTypeException */ public function addRow( array $row ) { foreach( $row as &$col ) { @@ -64,6 +64,17 @@ public function addRow( array $row ) { fwrite($this->tmpStream, json_encode($row) . "\n"); } + /** + * Append multiple rows of data to the end of the Worksheet. + * + * @param array|\Iterator $dataSet An iterable of arrays of scalars. + */ + public function addRows( $dataSet ) { + foreach( $dataSet as $row ) { + $this->addRow($row); + } + } + /** * Return the current value * @@ -100,7 +111,7 @@ public function key() { /** * Checks if current position is valid * - * @return boolean + * @return bool */ public function valid() { return $this->currentValue !== null; diff --git a/src/EngineInterface.php b/src/EngineInterface.php index 3ff6402..f8f6566 100644 --- a/src/EngineInterface.php +++ b/src/EngineInterface.php @@ -6,13 +6,14 @@ interface EngineInterface { /** * @param \Quorum\Exporter\DataSheet $sheet - * @return mixed + * @return void * @access private */ public function processSheet( DataSheet $sheet ); /** * @param resource $outputStream + * @return void * @access private */ public function outputToStream( $outputStream ); diff --git a/src/Engines/CsvEngine.php b/src/Engines/CsvEngine.php index bb79b1e..acd3f6d 100644 --- a/src/Engines/CsvEngine.php +++ b/src/Engines/CsvEngine.php @@ -280,6 +280,8 @@ final protected function isLittleEndian() { } /** + * Whether to disable the leading Byte Order Mark for the given encoding from being output. + * * @param bool $disable */ public function disableBom( $disable = true ) {