Add detailed docstrings for public methods (#170)

Each method across multiple files is now accompanied by detailed
docstrings for a more comprehensive understanding of their
functionality. The docstrings elucidate the purpose, behavior and return
types of each method. A clearer understanding of these methods will
facilitate both the future development and maintenance of the codebase.

src/Analyze/Analyzer.php

@@ -23,6 +23,10 @@
 
 final class Analyzer
 {
+    /**
+     * Creates a new instance of the class.
+     * @param string $csvFilename the filename of the CSV file to be parsed
+     */
     public function __construct(
         private string $csvFilename,
     ) {
@@ -31,7 +35,7 @@ public function __construct(
     /**
      * Analyzes a CSV file and suggests parameters for parsing and creating a schema.
      * @param  null|bool $forceHeader Whether to force the presence of a header row. Null to auto-detect.
-     * @param  int       $lineLimit   Number of lines to read when detecting parameters. Default is 1000.
+     * @param  int       $lineLimit   number of lines to read when detecting parameters
      * @return Schema    the suggested schema for the CSV file
      */
     public function analyzeCsv(?bool $forceHeader = null, int $lineLimit = 1000): Schema

src/CliApplication.php

@@ -26,6 +26,10 @@ final class CliApplication extends \JBZoo\Cli\CliApplication
         '                                /_/                    ',
     ];
 
+    /**
+     * Retrieves the long version of the application.
+     * @return string the long version of the application
+     */
     public function getLongVersion(): string
     {
         $logo = '<info>' . \implode("</info>\n<info>", $this->appLogo) . '</info>';

src/Csv/Column.php

@@ -33,38 +33,62 @@ final class Column
 
     private ?int  $csvOffset = null;
     private int   $schemaId;
-    private Data  $data;
+    private Data  $internalData;
     private array $rules;
     private array $aggRules;
 
     public function __construct(int $schemaId, array $config)
     {
         $this->schemaId = $schemaId;
-        $this->data = new Data($config);
+        $this->internalData = new Data($config);
         $this->rules = $this->prepareRuleSet('rules');
         $this->aggRules = $this->prepareRuleSet('aggregate_rules');
     }
 
+    /**
+     * Retrieves the name from the internal data object.
+     * @return string The name value retrieved from the internal data object. If the name
+     *                does not exist, the method will return the fallback name value
+     *                defined in the class constant FALLBACK_VALUES.
+     */
     public function getName(): string
     {
-        return $this->data->getString('name', self::FALLBACK_VALUES['name']);
+        return $this->internalData->getString('name', self::FALLBACK_VALUES['name']);
     }
 
+    /**
+     * Returns the CSV offset.
+     * @return null|int the CSV offset if set, or null if not set
+     */
     public function getCsvOffset(): ?int
     {
         return $this->csvOffset;
     }
 
+    /**
+     * Returns the schema ID.
+     * @return int the schema ID
+     */
     public function getSchemaId(): int
     {
         return $this->schemaId;
     }
 
+    /**
+     * Gets the description from the internal data, or the fallback value if it is not set.
+     * @return string the description value
+     */
     public function getDescription(): string
     {
-        return $this->data->getString('description', self::FALLBACK_VALUES['description']);
+        return $this->internalData->getString('description', self::FALLBACK_VALUES['description']);
     }
 
+    /**
+     * Retrieves the human-friendly name of the object.
+     * If the CSV offset is not null, the CSV offset is used as the prefix. Otherwise, the schema ID is used as the
+     * prefix. The prefix is then concatenated with a colon (:) character and the trimmed name of the object.
+     * @return string the human-friendly name of the object
+     */
     public function getHumanName(): string
     {
         if ($this->csvOffset !== null) {
@@ -76,46 +100,84 @@ public function getHumanName(): string
         return $prefix . ':' . \trim($this->getName());
     }
 
+    /**
+     * Checks whether the object is required.
+     * Retrieves the boolean value of 'required' from the internal data.
+     * If the value is not found, it falls back to the default value defined in FALLBACK_VALUES array.
+     * @return bool indicates whether the object is required
+     */
     public function isRequired(): bool
     {
-        return $this->data->getBool('required', self::FALLBACK_VALUES['required']);
+        return $this->internalData->getBool('required', self::FALLBACK_VALUES['required']);
     }
 
+    /**
+     * Retrieves the rules associated with the object.
+     * The method simply returns the rules property of the object.
+     * @return array the rules associated with the object
+     */
     public function getRules(): array
     {
         return $this->rules;
     }
 
+    /**
+     * Retrieves the aggregate rules associated with the object.
+     * @return array the aggregate rules associated with the object
+     */
     public function getAggregateRules(): array
     {
         return $this->aggRules;
     }
 
+    /**
+     * Retrieves the validator for the column.
+     * Creates and returns a new instance of the ValidatorColumn class, initialized with the current object.
+     * The ValidatorColumn class is responsible for validating the column based on certain rules and criteria.
+     * @return ValidatorColumn the validator for the column
+     */
     public function getValidator(): ValidatorColumn
     {
         return new ValidatorColumn($this);
     }
 
+    /**
+     * Validates a cell value using the validator associated with this object.
+     * If the line number is not specified, it defaults to Error::UNDEFINED_LINE.
+     * The cell value is passed to the underlying validator to perform the validation.
+     * @param  string     $cellValue the value of the cell to validate
+     * @param  int        $line      the line number where the cell is located
+     * @return ErrorSuite the validation result as an ErrorSuite object
+     */
     public function validateCell(string $cellValue, int $line = Error::UNDEFINED_LINE): ErrorSuite
     {
         return $this->getValidator()->validateCell($cellValue, $line);
     }
 
+    /**
+     * Sets the CSV offset.
+     * @param int $csvOffset the CSV offset to be set
+     */
     public function setCsvOffset(int $csvOffset): void
     {
         $this->csvOffset = $csvOffset;
     }
 
+    /**
+     * Retrieves a clone of the internal Data object.
+     * The method clones the internalData object and returns the clone to prevent modification of the internal data.
+     * @return Data a cloned instance of the internal Data object
+     */
     public function getData(): Data
     {
-        return clone $this->data;
+        return clone $this->internalData; // Clone to prevent modification of the internal data
     }
 
     private function prepareRuleSet(string $schemaKey): array
     {
         $rules = [];
 
-        $ruleSetConfig = $this->data->getSelf($schemaKey, [])->getArrayCopy();
+        $ruleSetConfig = $this->internalData->getSelf($schemaKey, [])->getArrayCopy();
         foreach ($ruleSetConfig as $ruleName => $ruleValue) {
             $rules[$ruleName] = $ruleValue;
         }

src/Csv/CsvFile.php

@@ -27,11 +27,11 @@
 
 final class CsvFile
 {
-    private string          $csvFilename;
-    private LeagueReader    $reader;
-    private Schema          $schema;
-    private bool            $isEmpty;
-    private ?array          $header = null;
+    private string       $csvFilename;
+    private LeagueReader $reader;
+    private Schema       $schema;
+    private bool         $isEmpty;
+    private ?array       $header = null;
 
     public function __construct(string $csvFilename, null|array|string $csvSchemaFilenameOrArray = null)
     {
@@ -45,13 +45,21 @@ public function __construct(string $csvFilename, null|array|string $csvSchemaFil
         $this->reader = $this->prepareReader();
     }
 
+    /**
+     * Returns the CSV filename.
+     * @return string the CSV filename
+     */
     public function getCsvFilename(): string
     {
         return $this->csvFilename;
     }
 
     /**
-     * @return string[]
+     * Returns the header array.
+     * The header array contains the column names or indexes of the CSV file.
+     * If the CSV file has a header row, it will return the column names.
+     * If the CSV file does not have a header row, it will return the column indexes.
+     * @return string[] the header array
      */
     public function getHeader(): array
     {
@@ -69,6 +77,11 @@ public function getHeader(): array
         return $this->header;
     }
 
+    /**
+     * Retrieve the records from the CSV reader.
+     * @param  null|int  $offset The offset of the column to fetch records from
+     * @return \Iterator the iterator of records
+     */
     public function getRecords(?int $offset = null): \Iterator
     {
         if ($offset !== null) {
@@ -80,28 +93,49 @@ public function getRecords(?int $offset = null): \Iterator
         return $records;
     }
 
+    /**
+     * Retrieves a chunk of records from the TabularDataReader.
+     * @param  int               $offset the starting offset of the chunk
+     * @param  int               $limit  the maximum number of records to retrieve in the chunk
+     * @return TabularDataReader the TabularDataReader object containing the records
+     */
     public function getRecordsChunk(int $offset = 0, int $limit = -1): TabularDataReader
     {
         return Statement::create(null, $offset, $limit)->process($this->reader, []); // No headers is required!
     }
 
+    /**
+     * @param  bool       $quickStop Whether to stop validation after encountering the first error
+     * @return ErrorSuite The error suite containing any validation errors
+     */
     public function validate(bool $quickStop = false): ErrorSuite
     {
         return (new ValidatorCsv($this, $this->schema))->validate($quickStop);
     }
 
+    /**
+     * Get the number of columns in the real dataset.
+     * @return int the total number of columns in the real dataset
+     */
     public function getRealColumNumber(): int
     {
         return \count($this->getRecordsChunk(0, 1)->first());
     }
 
+    /**
+     * Returns the schema object associated with this instance.
+     * @return Schema the schema object
+     */
     public function getSchema(): Schema
     {
         return $this->schema;
     }
 
     /**
-     * @return Column[]
+     * Retrieves the columns mapped by header.
+     * @param  null|ErrorSuite $errors an instance of ErrorSuite to store any errors encountered during mapping
+     * @return Column[]        an associative array where the keys represent the CSV header index and the values
+     *                         represent the corresponding CSV Column objects
      */
     public function getColumnsMappedByHeader(?ErrorSuite $errors = null): array
     {
@@ -149,7 +183,9 @@ public function getColumnsMappedByHeader(?ErrorSuite $errors = null): array
     }
 
     /**
-     * @return string[]
+     * Retrieves only the header names from the columns mapped by header.
+     * @param  null|ErrorSuite $errors an instance of ErrorSuite to store any errors encountered during mapping
+     * @return string[]        an array containing only the names of the columns mapped by header
      */
     public function getColumnsMappedByHeaderNamesOnly(?ErrorSuite $errors = null): array
     {