general improvement of comments in code

src/Ifsnop/Mysqldump/Mysqldump.php

@@ -1,9 +1,9 @@
 <?php
 
 /**
- * PHP version of mysqldump cli that comes with MySQL
+ * PHP version of mysqldump cli that comes with MySQL.
  *
- * mysql mysqldump pdo php7 php5 database php sql
+ * Tags: mysql mysqldump pdo php7 php5 database php sql hhvm mariadb mysql-backup.
  *
  * @category Library
  * @package  Ifsnop\Mysqldump
@@ -20,12 +20,9 @@
 use PDOException;
 
 /**
- * PHP version of mysqldump cli that comes with MySQL
- *
- * mysql mysqldump pdo php7 php5 database php sql
+ * Class Mysqldump.
  *
  * @category Library
- * @package  Ifsnop\Mysqldump
  * @author   Diego Torres <[email protected]>
  * @license  http://www.gnu.org/copyleft/gpl.html GNU General Public License
  * @link     https://github.com/ifsnop/mysqldump-php
@@ -34,40 +31,43 @@
 class Mysqldump
 {
 
-    // Same as mysqldump
+    // Same as mysqldump.
     const MAXLINESIZE = 1000000;
 
-    // Available compression methods as constants
-    const GZIP = 'Gzip';
+    // List of available compression methods as constants.
+    const GZIP  = 'Gzip';
     const BZIP2 = 'Bzip2';
-    const NONE = 'None';
+    const NONE  = 'None';
 
-    // Available connection strings
-    const UTF8 = 'utf8';
+    // List of available connection strings.
+    const UTF8    = 'utf8';
     const UTF8MB4 = 'utf8mb4';
 
     /**
-     * Database username
+     * Database username.
      * @var string
      */
     public $user;
+
     /**
-     * Database password
+     * Database password.
      * @var string
      */
     public $pass;
+
     /**
-     * Connection string for PDO
+     * Connection string for PDO.
      * @var string
      */
     public $dsn;
+
     /**
-     * Destination filename, defaults to stdout
+     * Destination filename, defaults to stdout.
      * @var string
      */
-    public $fileName = 'php://output';
+    public $fileName = 'php://stdout';
 
-    // Internal stuff
+    // Internal stuff.
     private $tables = array();
     private $views = array();
     private $triggers = array();
@@ -82,24 +82,27 @@ class Mysqldump
     private $version;
     private $tableColumnTypes = array();
     private $transformColumnValueCallable;
+
     /**
-     * database name, parsed from dsn
+     * Database name, parsed from dsn.
      * @var string
      */
     private $dbName;
+
     /**
-     * host name, parsed from dsn
+     * Host name, parsed from dsn.
      * @var string
      */
     private $host;
+
     /**
-     * dsn string parsed as an array
+     * Dsn string parsed as an array.
      * @var array
      */
     private $dsnArray = array();
 
     /**
-     * Keyed on table name, with the value as the conditions
+     * Keyed on table name, with the value as the conditions.
      * e.g. - 'users' => 'date_registered > NOW() - INTERVAL 6 MONTH'
      *
      * @var array
@@ -168,7 +171,7 @@ public function __construct(
         $this->pass = $pass;
         $this->parseDsn($dsn);
 
-        // this drops MYSQL dependency, only use the constant if it's defined
+        // This drops MYSQL dependency, only use the constant if it's defined.
         if ("mysql" === $this->dbType) {
             $pdoSettingsDefault[PDO::MYSQL_ATTR_USE_BUFFERED_QUERY] = false;
         }
@@ -200,7 +203,6 @@ public function __construct(
 
     /**
      * Destructor of Mysqldump. Unsets dbHandlers and database objects.
-     *
      */
     public function __destruct()
     {
@@ -209,7 +211,7 @@ public function __destruct()
 
     /**
      * Custom array_replace_recursive to be used if PHP < 5.3
-     * Replaces elements from passed arrays into the first array recursively
+     * Replaces elements from passed arrays into the first array recursively.
      *
      * @param array $array1 The array in which elements are replaced
      * @param array $array2 The array from which elements will be extracted
@@ -246,7 +248,7 @@ public function setTableWheres(array $tableWheres)
     /**
      * @param $tableName
      *
-     * @return bool|mixed
+     * @return boolean|mixed
      */
     public function getTableWhere($tableName)
     {
@@ -273,7 +275,7 @@ public function setTableLimits(array $tableLimits)
     /**
      * Returns the LIMIT for the table.  Must be numeric to be returned.
      * @param $tableName
-     * @return bool
+     * @return boolean
      */
     public function getTableLimit($tableName)
     {
@@ -297,6 +299,7 @@ public function getTableLimit($tableName)
      *   mysql:unix_socket=/tmp/mysql.sock;dbname=testdb
      *
      * @param string $dsn dsn string to parse
+     * @return boolean
      */
     private function parseDsn($dsn)
     {
@@ -335,13 +338,13 @@ private function parseDsn($dsn)
     }
 
     /**
-     * Connect with PDO
+     * Connect with PDO.
      *
      * @return null
      */
     private function connect()
     {
-        // Connecting with PDO
+        // Connecting with PDO.
         try {
             switch ($this->dbType) {
                 case 'sqlite':
@@ -382,10 +385,11 @@ private function connect()
     }
 
     /**
-     * Main call
+     * Primary function, triggers dumping.
      *
      * @param string $filename  Name of file to write sql dump to
      * @return null
+     * @throws \Exception
      */
     public function start($filename = '')
     {
@@ -419,8 +423,8 @@ public function start($filename = '')
             }
         }
 
-        // Get table, view, trigger, procedures and events
-        // structures from database
+        // Get table, view, trigger, procedures and events structures from
+        // database.
         $this->getDatabaseStructureTables();
         $this->getDatabaseStructureViews();
         $this->getDatabaseStructureTriggers();
@@ -436,7 +440,7 @@ public function start($filename = '')
         // If there still are some tables/views in include-tables array,
         // that means that some tables or views weren't found.
         // Give proper error and exit.
-        // This check will be removed once include-tables supports regexps
+        // This check will be removed once include-tables supports regexps.
         if (0 < count($this->dumpSettings['include-tables'])) {
             $name = implode(",", $this->dumpSettings['include-tables']);
             throw new Exception("Table (".$name.") not found in database");
@@ -448,18 +452,20 @@ public function start($filename = '')
         $this->exportProcedures();
         $this->exportEvents();
 
-        // Restore saved parameters
+        // Restore saved parameters.
         $this->compressManager->write(
             $this->typeAdapter->restore_parameters()
         );
-        // Write some stats to output file
+        // Write some stats to output file.
         $this->compressManager->write($this->getDumpFileFooter());
-        // Close output file
+        // Close output file.
         $this->compressManager->close();
+
+        return;
     }
 
     /**
-     * Returns header for dump file
+     * Returns header for dump file.
      *
      * @return string
      */
@@ -485,7 +491,7 @@ private function getDumpFileHeader()
     }
 
     /**
-     * Returns footer for dump file
+     * Returns footer for dump file.
      *
      * @return string
      */
@@ -618,7 +624,7 @@ private function getDatabaseStructureEvents()
      * Compare if $table name matches with a definition inside $arr
      * @param $table string
      * @param $arr array with strings or patterns
-     * @return bool
+     * @return boolean
      */
     private function matches($table, $arr)
     {