Fix phpdocs SchemaCache, Command and Connection classes. (#569)

src/Cache/SchemaCache.php

@@ -143,8 +143,9 @@ public function isEnabled(): bool
     }
 
     /**
-     * Whether to enable schema caching. Note that in order to enable truly schema caching, a valid cache component as
-     * specified must be enabled and must be set true.
+     * Whether to enable schema caching.
+     *
+     * Note that to enable truly schema caching, a valid cache part as specified must be enabled and must be set true.
      *
      * @param bool $value Whether to enable schema caching.
      *
@@ -170,8 +171,9 @@ public function setDuration(int|null $value): void
     }
 
     /**
-     * List of tables whose metadata should NOT be cached. Defaults to empty array. The table names may contain schema
-     * prefix, if any. Do not quote the table names.
+     * List of tables whose metadata shouldn't be cached.
+     *
+     * Defaults to an empty array. The table names may contain schema prefix, if any. Don't quote the table names.
      *
      * @param array $value The table names.
      *
@@ -185,9 +187,10 @@ public function setExclude(array $value): void
     /**
      * Normalizes the cache key from a given key.
      *
-     * If the given key is a string that does not contain characters `{}()/\@:` and no more than 64 characters, then the
-     * key will be returned back as it is, integers will be converted to strings. Otherwise, a normalized key is
-     * generated by serializing the given key and applying MD5 hashing.
+     * If the given key is a string that doesn't contain characters `{}()/\@:` and no more than 64 characters, then the
+     * key will be returned back as it's, integers will be converted to strings.
+     *
+     * Otherwise, a normalized key is generated by serializing the given key and applying MD5 hashing.
      *
      * @link https://www.php-fig.org/psr/psr-16/#12-definitions
      *

src/Command/AbstractCommand.php

@@ -29,7 +29,7 @@
 use function strncmp;
 
 /**
- * Represents a SQL statement to be executed against a database.
+ * Represents an SQL statement to be executed against a database.
  *
  * A command object is usually created by calling {@see \Yiisoft\Db\Connection\ConnectionInterface::createCommand()}.
  *
@@ -48,7 +48,7 @@
  *
  * Abstract command supports SQL statement preparation and parameter binding.
  *
- * Call {@see bindValue()} to bind a value to a SQL parameter;
+ * Call {@see bindValue()} to bind a value to a SQL parameter.
  * Call {@see bindParam()} to bind a PHP variable to a SQL parameter.
  *
  * When binding a parameter, the SQL statement is automatically prepared. You may also call {@see prepare()} explicitly
@@ -66,7 +66,7 @@
  * )->execute();
  * ```
  *
- * To build SELECT SQL statements, please use {@see \Yiisoft\Db\Query\QueryInterface} instead.
+ * To build SELECT SQL statements, please use {@see QueryInterface} instead.
  */
 abstract class AbstractCommand implements CommandInterface
 {
@@ -605,7 +605,7 @@ protected function reset(): void
     }
 
     /**
-     * Checks if the query mode is read mode.
+     * Checks if the query mode is a read mode.
      */
     private function isReadMode(int $queryMode): bool
     {

src/Command/Param.php

@@ -7,11 +7,14 @@
 use Yiisoft\Db\Expression\ExpressionInterface;
 
 /**
- * Represents a parameter used in building a SQL statement. It can be used to represent a placeholder in a SQL
- * statement, and can be bound to a specific value when the statement is executed. It can also represent a column name
- * or table name, depending on the context in which it is used. The class provides methods for specifying the parameter
- * name, value, as well as methods for quoting and escaping the parameter value to ensure that it is properly handled by
- * the database.
+ * Represents a parameter used in building an SQL statement.
+ *
+ * It can be used to represent a placeholder in an SQL statement, and can be bound to a specific value when the
+ * statement is executed.
+ *
+ * It can also represent a column name or table name, depending on the context in which it's
+ * used. The class provides methods for specifying the parameter name, value, as well as methods for quoting and
+ * escaping the parameter value to ensure that it's handled by the database.
  */
 final class Param implements ParamInterface, ExpressionInterface
 {

src/Command/ParamInterface.php

@@ -5,14 +5,14 @@
 namespace Yiisoft\Db\Command;
 
 /**
- * This interface represents a parameter to be bound to a SQL statement.
+ * This interface represents a parameter to be bound to an SQL statement.
  */
 interface ParamInterface
 {
     /**
      * @param mixed $value The value to bind to the parameter.
-     * @param int $type The SQL data type of the parameter. If null, the type is determined by the PHP type of the
-     * value.
+     * @param int $type The SQL data type of the parameter.
+     * If null, the type is determined by the PHP type of the value.
      */
     public function __construct(mixed $value, int $type);
 

src/Connection/AbstractConnection.php

@@ -18,8 +18,10 @@
 use Yiisoft\Db\Transaction\TransactionInterface;
 
 /**
- * Represents a connection to a database. It provides methods for interacting with the database, such as executing SQL
- * queries and performing data manipulation.
+ * Represents a connection to a database.
+ *
+ * It provides methods for interacting with the database, such as executing SQL queries and performing data
+ * manipulation.
  */
 abstract class AbstractConnection implements ConnectionInterface, LoggerAwareInterface
 {
@@ -106,14 +108,16 @@ public function transaction(Closure $closure, string $isolationLevel = null): mi
     }
 
     /**
-     * Rolls back given {@see TransactionInterface} object if it's still active and level match. In some cases rollback
-     * can fail, so this method is fail-safe. Exceptions thrown from rollback will be caught and just logged with
-     * {@see logger->log()}.
+     * Rolls back given {@see TransactionInterface} an object if it's still active and level match.
+     *
+     * Sometimes, rollback can fail, so this method is fail-safe.
+     *
+     * Exceptions thrown from rollback will be caught and just logged with {@see logger->log()}.
      *
      * @param TransactionInterface $transaction TransactionInterface object given from {@see beginTransaction()}.
      * @param int $level TransactionInterface level just after {@see beginTransaction()} call.
      *
-     * @throws Throwable If transaction was not rolled back.
+     * @throws Throwable If transaction wasn't rolled back.
      */
     private function rollbackTransactionOnLevel(TransactionInterface $transaction, int $level): void
     {

src/Connection/AbstractDsn.php

@@ -9,7 +9,7 @@
 use function implode;
 
 /**
- * it's typically used to parse a DSN string, which is a string that contains all the necessary information to connect
+ * It's typically used to parse a DSN string, which is a string that has all the necessary information to connect
  * to a database, such as the database driver, hostname, database name, port and options.
  *
  * It also allows you to access individual components of the DSN, such as the driver or the database name.
@@ -50,7 +50,7 @@ public function asString(): string
     }
 
     /**
-     * @return string The Data Source Name, or DSN, contains the information required to connect to the database.
+     * @return string The Data Source Name, or DSN, has the information required to connect to the database.
      */
     public function __toString(): string
     {
@@ -90,7 +90,7 @@ public function getOptions(): array
     }
 
     /**
-     * @return string|null The database port. Null if not set.
+     * @return string|null The database port. Null if isn't set.
      */
     public function getPort(): string|null
     {

src/Connection/AbstractDsnSocket.php

@@ -9,7 +9,7 @@
 use function implode;
 
 /**
- * It's typically used to parse a DSN string, which is a string that contains all the necessary information to connect
+ * It's typically used to parse a DSN string, which is a string that has all the necessary information to connect
  * to a database, such as the database driver, unix socket, database name, options.
  *
  * It also allows you to access individual components of the DSN, such as the driver or the database name.
@@ -45,7 +45,7 @@ public function asString(): string
     }
 
     /**
-     * @return string The Data Source Name, or DSN, contains the information required to connect to the database.
+     * @return string The Data Source Name, or DSN, has the information required to connect to the database.
      */
     public function __toString(): string
     {

src/Connection/ConnectionInterface.php

@@ -83,18 +83,18 @@ public function createTransaction(): TransactionInterface;
     public function close(): void;
 
     /**
-     * Return cache key as array.
+     * Return a cache key as an array.
      *
-     * For example in PDO implementation: [$dsn, $username]
+     * For example, in PDO implementation: [$dsn, $username]
      *
-     * @return array The cache key as array.
+     * @return array The cache key as an array.
      */
     public function getCacheKey(): array;
 
     /**
      * Returns the name of the DB driver for the current `dsn`.
      *
-     * Use this method for informational purposes only.
+     * Use this method for information only.
      *
      * @return string The name of the DB driver for the current `dsn`.
      */
@@ -153,9 +153,9 @@ public function getTablePrefix(): string;
      * Obtains the schema information for the named table.
      *
      * @param string $name The table name.
-     * @param bool $refresh Whether to reload the table schema even if it is found in the cache.
+     * @param bool $refresh Whether to reload the table schema even if it's found in the cache.
      *
-     * @return TableSchemaInterface|null The schema information for the named table. Null if the named table does not
+     * @return TableSchemaInterface|null The schema information for the named table. Null if the named table doesn't
      * exist.
      */
     public function getTableSchema(string $name, bool $refresh = false): TableSchemaInterface|null;
@@ -192,13 +192,14 @@ public function open(): void;
     /**
      * Quotes a value for use in a query.
      *
-     * @return mixed The properly quoted string.
+     * @return mixed The quoted string.
      */
     public function quoteValue(mixed $value): mixed;
 
     /**
-     * Whether to enable [savepoint](http://en.wikipedia.org/wiki/Savepoint). Note that if the underlying DBMS does not
-     * support savepoint, setting this property to be true will have no effect.
+     * Whether to enable [savepoint](http://en.wikipedia.org/wiki/Savepoint).
+     *
+     * Note that if the underlying DBMS doesn't support savepoint, setting this property to be true will have no effect.
      *
      * @param bool $value Whether to enable savepoint.
      */
@@ -226,7 +227,7 @@ public function setTablePrefix(string $value): void;
      * @param string|null $isolationLevel The isolation level to use for this transaction.
      * {@see TransactionInterface::begin()} for details.
      *
-     * @throws Throwable If there is any exception during query. In this case the transaction will be rolled back.
+     * @throws Throwable If there is any exception during query. In this case, the transaction will be rolled back.
      *
      * @return mixed Result of callback function.
      */

src/Connection/ConnectionPoolInterface.php

@@ -9,58 +9,60 @@
 
 /**
  * This interface represents a connection pool. It provides a way to get a connection from the pool. It also provides
- * methods to set and get the master and slave connections.
+ * methods to set and get the primary and secondary connections.
  */
 interface ConnectionPoolInterface
 {
     /**
      * Whether to enable read/write splitting by using {@see slaves} to read data.
      *
-     * Note that if {@see slaves} is empty, read/write splitting will NOT be enabled no matter what value this property
+     * Note that if {@see slaves} is empty, read/write splitting won't be enabled no matter what value this property
      * takes.
      */
-    public function areSlavesEnabled(): bool;
+    public function areSecondaryEnabled(): bool;
 
     /**
-     * Returns the currently active master connection.
+     * Returns the currently active primary connection.
      *
-     * If this method is called for the first time, it will try to open a master connection.
+     * If this method is called for the first time, it will try to open a primary connection.
      *
-     * @return ConnectionInterface|null The currently active master connection. `null` is returned if there is no master
-     * available.
+     * @return ConnectionInterface|null The currently active primary connection. `Null` is returned if there is no
+     * primary available.
      */
-    public function getMaster(): ConnectionInterface|null;
+    public function getPrimary(): ConnectionInterface|null;
 
     /**
-     * Returns the currently active slave connection.
+     * Returns the currently active secondary connection.
      *
-     * If this method is called for the first time, it will try to open a slave connection when {@see setEnableSlaves()}
+     * If this method is called for the first time, it will try to open a secondary connection when
+     * {@see setEnableSecondary()}
      * is true.
      *
-     * @param bool $fallbackToMaster Whether to return a master connection in case there is no slave connection
+     * @param bool $fallbackToMaster Whether to return a primary connection in case there is no secondary connection
      * available.
      *
-     * @return ConnectionInterface|null The currently active slave connection. `null` is returned if there is no slave
-     * available and `$fallbackToMaster` is false.
+     * @return ConnectionInterface|null The currently active secondary connection. `Null` is returned if there is no
+     * secondary available and `$fallbackToMaster` is false.
      */
-    public function getSlave(bool $fallbackToMaster = true): ConnectionInterface|null;
+    public function getSecondary(bool $fallbackToMaster = true): ConnectionInterface|null;
 
     /**
-     * Whether to enable read/write splitting by using {@see setSlaves()} to read data. Note that if {@see setSlaves()}
-     * is empty, read/write splitting will NOT be enabled no matter what value this property takes.
+     * Whether to enable read/write splitting by using {@see setSecondary()} to read data.
+     * Note that if {@see setSecondary()} is empty, read/write splitting won't be enabled no matter what value this
+     * property takes.
      */
-    public function setEnableSlaves(bool $value): void;
+    public function setEnableSecondary(bool $value): void;
 
     /**
-     * Set connection for master server, you can specify multiple connections, adding the id for each one.
+     * Set connection for primary server, you can specify many connections, adding the id for each one.
      *
-     * @param string $key Index master connection.
-     * @param ConnectionInterface $master The connection every master.
+     * @param string $key Index primary connection.
+     * @param ConnectionInterface $master The connection every primary.
      */
-    public function setMaster(string $key, ConnectionInterface $master): void;
+    public function setPrimary(string $key, ConnectionInterface $master): void;
 
     /**
-     * The retry interval in seconds for dead servers listed in {@see setMaster()} and {@see setSlave()}.
+     * The retry interval in seconds for dead servers listed in {@see setPrimary()} and {@see setSecondary()}.
      *
      * @param int $value The retry interval in seconds.
      */
@@ -71,21 +73,23 @@ public function setServerRetryInterval(int $value): void;
      *
      * @param bool $value Whether to shuffle {@see setMaster()} before getting one.
      */
-    public function setShuffleMasters(bool $value): void;
+    public function setShufflePrimary(bool $value): void;
 
     /**
-     * Set connection for master slave, you can specify multiple connections, adding the id for each one.
+     * Set connection for a primary secondary, you can specify many connections, adding the id for each one.
      *
-     * @param string $key Index slave connection.
-     * @param ConnectionInterface $slave The connection every slave.
+     * @param string $key Index secondary connection.
+     * @param ConnectionInterface $slave The connection every secondary.
      */
     public function setSlave(string $key, ConnectionInterface $slave): void;
 
     /**
-     * Executes the provided callback by using the master connection.
+     * Executes the provided callback by using the primary connection.
+     *
+     * This method is provided so that you can temporarily force using the primary connection to perform DB operations
+     * even if they're read queries.
      *
-     * This method is provided so that you can temporarily force using the master connection to perform DB operations
-     * even if they are read queries. For example,
+     * For example,
      *
      * ```php
      * $result = $db->useMaster(function (ConnectionInterface $db) {
@@ -94,7 +98,7 @@ public function setSlave(string $key, ConnectionInterface $slave): void;
      * ```
      *
      * @param Closure $closure a PHP Closure to be executed by this method.
-     * Its signature is `function (ConnectionInterface $db)`. Its return value will be returned by this method.
+     * Its signature is `function (ConnectionInterface $db)`. This method will return its return value.
      *
      * @throws Throwable If there is any exception thrown from the callback.
      *

src/Connection/DsnInterface.php

@@ -5,13 +5,16 @@
 namespace Yiisoft\Db\Connection;
 
 /**
- * This interface represents a Data Source Name. It is used to configure a {@see ConnectionInterface} instance. The DSN
- * string format is described in {@see asString()}.
+ * This interface represents a Data Source Name.
+ *
+ * It's used to configure a {@see ConnectionInterface} instance.
+ *
+ * The DSN string format is described in {@see asString()}.
  */
 interface DsnInterface
 {
     /**
-     * @return string The Data Source Name, or DSN, contains the information required to connect to the database.
+     * @return string The Data Source Name, or DSN, has the information required to connect to the database.
      *
      * Please refer to the [PHP manual](http://php.net/manual/en/pdo.construct.php) on the format of the DSN string.
      *