phpdoc fixes (#604)

src/Command/ParamInterface.php

@@ -5,7 +5,7 @@
 namespace Yiisoft\Db\Command;
 
 /**
- * This interface represents a parameter to be bound to an SQL statement.
+ * This interface represents a parameter to bind to an SQL statement.
  */
 interface ParamInterface
 {

src/Connection/ConnectionInterface.php

@@ -48,7 +48,7 @@ public function beginTransaction(string $isolationLevel = null): TransactionInte
     /**
      * Create a batch query result instance.
      *
-     * @param QueryInterface $query The query to be executed.
+     * @param QueryInterface $query The query to execute.
      * @param bool $each Whether to return each row of the result set one at a time.
      *
      * @return BatchQueryResultInterface The batch query result instance.
@@ -58,8 +58,8 @@ public function createBatchQueryResult(QueryInterface $query, bool $each = false
     /**
      * Creates a command for execution.
      *
-     * @param string|null $sql The SQL statement to be executed.
-     * @param array $params The parameters to be bound to the SQL statement.
+     * @param string|null $sql The SQL statement to execute.
+     * @param array $params The parameters to bind to the SQL statement.
      *
      * @throws Exception
      * @throws InvalidConfigException
@@ -171,9 +171,9 @@ public function getTableSchema(string $name, bool $refresh = false): TableSchema
     public function getTransaction(): TransactionInterface|null;
 
     /**
-     * Returns a value indicating whether the DB connection is established.
+     * Returns a value indicating whether the DB connection is active.
      *
-     * @return bool Whether the DB connection is established.
+     * @return bool Whether the DB connection is active.
      */
     public function isActive(): bool;
 
@@ -185,7 +185,7 @@ public function isSavepointEnabled(): bool;
     /**
      * Establishes a DB connection.
      *
-     * It does nothing if a DB connection has already been established.
+     * It does nothing if a DB connection is active.
      *
      * @throws Exception
      * @throws InvalidConfigException If connection fails.
@@ -219,8 +219,10 @@ public function setEnableSavepoint(bool $value): void;
     public function setProfiler(ProfilerInterface|null $profiler): void;
 
     /**
-     * The common prefix or suffix for table names. If a table name is given as `{{%TableName}}`, then the percentage
-     * character `%` will be replaced with this property value. For example, `{{%post}}` becomes `{{tbl_post}}`.
+     * The common prefix or suffix for table names.
+     * If a table name is `{{%TableName}}`, then the percentage
+     * character `%` will be replaced with this property value.
+     * For example, `{{%post}}` becomes `{{tbl_post}}`.
      *
      * @param string $value The common prefix or suffix for table names.
      */

src/Connection/DsnInterface.php

@@ -7,7 +7,7 @@
 /**
  * Represents a Data Source Name (DSN) that's used to configure a {@see ConnectionInterface} instance.
  *
- * The DSN string format is described in {@see asString()}.
+ * For DSN string format see {@see DsnInterface::asString()}.
  */
 interface DsnInterface
 {

src/Constraint/ConstraintSchemaInterface.php

@@ -5,10 +5,13 @@
 namespace Yiisoft\Db\Constraint;
 
 /**
- * Represents the methods that are required to work with constraints in a database, as getting the name of the
- * constraint, the columns that the constraint is applied to, and the type of constraint.
+ * Defines the methods to get information about database constraints:
  *
- * A constraint is a rule that's applied to the data in a table to ensure the integrity and correctness of the data.
+ * - Name of the constraint
+ * - Columns that the constraint applies to
+ * - Type of constraint
+ *
+ * A constraint is a rule that's applied to enforce the integrity and correctness of the data.
  */
 interface ConstraintSchemaInterface
 {
@@ -17,7 +20,7 @@ interface ConstraintSchemaInterface
      *
      * @param string $schema The schema of the tables. Defaults to empty string, meaning the current or default schema
      * name.
-     * @param bool $refresh Whether to fetch the latest available table schemas. If this is false, cached data may be
+     * @param bool $refresh Whether to fetch the latest available table schemas. If this is `false`, cached data may be
      * returned if available.
      *
      * @return array The check constraints for all tables in the database. Each array element is an array of the
@@ -30,7 +33,7 @@ public function getSchemaChecks(string $schema = '', bool $refresh = false): arr
      *
      * @param string $schema The schema of the tables. Defaults to empty string, meaning the current or default schema
      * name.
-     * @param bool $refresh Whether to fetch the latest available table schemas. If this is false, cached data may be
+     * @param bool $refresh Whether to fetch the latest available table schemas. If this is `false`, cached data may be
      * returned if available.
      *
      * @return array The default value constraints for all tables in the database. Each array element is an array of
@@ -43,7 +46,7 @@ public function getSchemaDefaultValues(string $schema = '', bool $refresh = fals
      *
      * @param string $schema The schema of the tables. Defaults to empty string, meaning the current or default schema
      * name.
-     * @param bool $refresh Whether to fetch the latest available table schemas. If this is false, cached data may be
+     * @param bool $refresh Whether to fetch the latest available table schemas. If this is `false`, cached data may be
      * returned if available.
      *
      * @return array The foreign keys for all tables in the database. Each array element is an array of the following
@@ -82,7 +85,7 @@ public function getSchemaPrimaryKeys(string $schema = '', bool $refresh = false)
      *
      * @param string $schema The schema of the tables. Defaults to empty string, meaning the current or default schema
      * name.
-     * @param bool $refresh Whether to fetch the latest available table schemas. If this is false, cached data may be
+     * @param bool $refresh Whether to fetch the latest available table schemas. If this is `false`, cached data may be
      * returned if available.
      *
      * @return array The unique constraints for all tables in the database. Each array element is an array of the

src/Driver/PDO/ConnectionPDOInterface.php

@@ -10,8 +10,8 @@
 use Yiisoft\Db\Exception\InvalidConfigException;
 
 /**
- * This interface defines a set of methods that must be implemented by a class to be used as a connection to a database
- * using {@see PDO} (PHP Data Objects).
+ * This interface defines a set of methods to implement in a class that allows to connect to a database
+ * with {@see PDO} (PHP Data Objects).
  */
 interface ConnectionPDOInterface extends ConnectionInterface
 {
@@ -32,7 +32,8 @@ public function getActivePDO(string $sql = '', bool $forRead = null): PDO|null;
      *
      * This property is mainly managed by {@see open()} and {@see close()} methods.
      *
-     * When a DB connection is active, this property will represent a PDO instance; otherwise, it will be null.
+     * When a DB connection is active, this property will represent a PDO instance.
+     * Otherwise, it will be `null`.
      *
      * @return PDO|null The PHP PDO instance associated with this DB connection.
      *
@@ -43,26 +44,28 @@ public function getPDO(): PDO|null;
     /**
      * Returns current DB driver.
      *
-     * @return PDODriverInterface - The driver used to create current connection.
+     * @return PDODriverInterface The driver used to create current connection.
      */
     public function getDriver(): PDODriverInterface;
 
     /**
-     * Return emulate prepare value.
+     * Whether to emulate prepared statements on PHP side.
+     *
+     * @see setEmulatePrepare()
      */
     public function getEmulatePrepare(): bool|null;
 
     /**
-     * Whether to turn on prepare emulation.
+     * Whether to turn on prepare statements emulation on PHP side.
      *
-     * Defaults to false, meaning {@see PDO} will use native-prepared support if available.
+     * Defaults to `false`, meaning {@see PDO} will use database prepared statements support if possible.
      *
-     * For some databases (such as MySQL), this may need to be set true so that {@see PDO} can emulate to preparing
-     * support to bypassing the buggy native prepare support.
+     * For some databases (such as MySQL), you may need to set it to `true` so that {@see PDO} can
+     * replace buggy prepared statements support provided by database itself.
      *
-     * The default value is null, which means the {@see PDO} `ATTR_EMULATE_PREPARES` value won't be changed.
+     * The default value is `null`, which means using default {@see PDO} `ATTR_EMULATE_PREPARES` value.
      *
-     * @param bool $value Whether to turn on prepare emulation.
+     * @param bool $value Whether to turn on prepared statement emulation.
      */
     public function setEmulatePrepare(bool $value): void;
 }

src/Driver/PDO/PDODriverInterface.php

@@ -8,20 +8,20 @@
 use Yiisoft\Db\Driver\DriverInterface;
 
 /**
- * This interface provides a set of methods that must be implemented by {@see PDO} (PHP Data Objects) driver classes.
+ * This interface provides a set of methods to implement by {@see PDO} (PHP Data Objects) driver classes.
  *
  * @link https://www.php.net/manual/en/book.pdo.php
  */
 interface PDODriverInterface extends DriverInterface
 {
     /**
-     * Set {@see PDO} attributes (name => value) that should be set when calling {@see open()} to establish a DB
+     * Set {@see PDO} attributes (name => value) to set when calling {@see open()} to establish a DB
      * connection.
      *
      * Please refer to the [PHP manual](https://php.net/manual/en/pdo.setattribute.php) for details about available
      * attributes.
      *
-     * @param array $attributes The attributes (name => value) to be set on the DB connection.
+     * @param array $attributes The attributes (name => value) to set on the DB connection.
      */
     public function attributes(array $attributes): void;
 
@@ -34,21 +34,22 @@ public function createConnection(): PDO;
 
     /**
      * Set charset used for database connection. The property is only used for MySQL, PostgresSQL databases. Defaults to
-     * null, meaning using default charset as configured by the database.
+     * `null`, meaning using default charset as configured by the database.
      *
      * For Oracle Database, the charset must be specified in the {@see dsn}, for example, for UTF-8 by appending
      * `;charset=UTF-8` to the DSN string.
      *
-     * The same applies for if you're using GBK or BIG5 charset with MySQL, then it's highly recommended specifying
+     * The same applies if you're using GBK or BIG5 charset with MySQL.
+     * In this case it's highly recommended specifying
      * charset via {@see dsn} like `'mysql:dbname=database;host=127.0.0.1;charset=GBK;'`.
      *
-     * @param string|null $charset The charset to be used for database connection.
+     * @param string|null $charset The charset to use for database connection.
      */
     public function charset(string|null $charset): void;
 
     /**
-     * @return string|null The charset of the pdo instance. Null is returned if the charset isn't set yet or not
-     * supported by the pdo driver
+     * @return string|null The charset of the pdo instance. If the charset isn't set yet or not
+     * supported by the PDO driver, it returns `null`.
      */
     public function getCharset(): string|null;
 
@@ -73,14 +74,14 @@ public function getPassword(): string;
     public function getUsername(): string;
 
     /**
-     * Set password for establishing DB connection. Defaults to `null` meaning no password to use.
+     * Set password for establishing DB connection. Defaults to `null` meaning use no password.
      *
      * @param string $password The password for establishing DB connection.
      */
     public function password(string $password): void;
 
     /**
-     * Set username for establishing DB connection. Defaults to `null` meaning no username to use.
+     * Set username for establishing DB connection. Defaults to `null` meaning use no username.
      *
      * @param string $username The username for establishing DB connection.
      */

src/Expression/ExpressionBuilderInterface.php

@@ -6,12 +6,12 @@
 
 /**
  * This interface defines the methods to build database expressions, such as conditions for a SELECT statement or values
- * to be inserted into a table.
+ * to insert into a table.
  *
- * These methods include creating comparison operators (e.g. "=", ">", "<"), combining expressions with logical
- * operators (e.g. "AND", "OR"), and building sub-queries.
+ * These methods include creating comparison operators (such as "=", ">", "<"), combining expressions with logical
+ * operators (such as "AND", "OR"), and building sub-queries.
  *
- * The interface provides a consistent way for developers to build expressions that can be used in different types of
+ * The interface provides a consistent way for developers to build expressions for various types of
  * database queries, without having to worry about the specific syntax of the underlying database.
  *
  * @see ExpressionInterface

src/Expression/ExpressionInterface.php

@@ -5,11 +5,12 @@
 namespace Yiisoft\Db\Expression;
 
 /**
- * This interface defines a set of methods that an object should implement to be used as an expression in database
- * queries, such as for filtering or ordering results.
+ * This interface defines a set of methods that an object should implement to represent an expression in database
+ * queries, such as one for filtering or ordering results.
  *
  * These methods include getting the expression as a string, getting the parameters to bind to the expression, and
- * getting the types of the parameters. Classes that implement this interface can be used in a variety of query building
+ * getting the types of the parameters.
+ * You can use classes that implement this interface in a variety of query building
  * methods provided by the library.
  *
  * The database abstraction layer of a Yii framework supports objects that implement this interface and will use

src/Profiler/ContextInterface.php

@@ -4,10 +4,13 @@
 
 namespace Yiisoft\Db\Profiler;
 
+/**
+ * Profiling context.
+ */
 interface ContextInterface
 {
     /**
-     * @return string Type of the context
+     * @return string Type of the context.
      */
     public function getType(): string;
 

src/Profiler/ProfilerInterface.php

@@ -5,7 +5,7 @@
 namespace Yiisoft\Db\Profiler;
 
 /**
- * Interface-decorator for work with `yiisoft\profiler` or another profiler.
+ * Interface-decorator to work with `yiisoft\profiler` or another profiler.
  *
  * @see \Yiisoft\Db\Connection\ConnectionInterface::setProfiler()
  */
@@ -14,9 +14,9 @@ interface ProfilerInterface
     /**
      * Marks the beginning of a code block for profiling.
      *
-     * This has to be matched with a call to {@see end()} with the same category name.
+     * There should be a matching call to {@see end()} with the same category name.
      *
-     * The begin and end calls must also be nested.
+     * The `begin()` and `end()` calls must also be properly nested.
      *
      * @param string $token Token for the code block.
      * @param array|ContextInterface $context The context data of this profile block.
@@ -26,7 +26,9 @@ public function begin(string $token, array|ContextInterface $context = []): void
     /**
      * Marks the end of a code block for profiling.
      *
-     * This has to be matched with an earlier call to {@see begin()} with the same category name.
+     * There should be a matching call to {@see begin()} with the same category name.
+     *
+     * The `begin()` and `end()` calls must also be properly nested.
      *
      * @param string $token Token for the code block.
      * @param array|ContextInterface $context The context data of this profile block.

src/Query/BatchQueryResultInterface.php

@@ -102,7 +102,7 @@ public function getQuery(): QueryInterface|null;
     public function getBatchSize(): int;
 
     /**
-     * @param int $value The number of rows to be returned in each batch.
+     * @param int $value The number of rows to return in each batch.
      */
     public function batchSize(int $value): self;
 

src/Query/QueryFunctionsInterface.php

@@ -9,9 +9,7 @@
 use Yiisoft\Db\Exception\InvalidConfigException;
 
 /**
- * This defines an interface for query functions.
- *
- * A query function is a function that can be called in a query to perform some operation on the data being selected or
+ * A query function is a function that's called in a query to perform operation on the data selected or
  * updated.
  *
  * Examples of query functions might include {@see count()}, {@see sum()}, {@see average()}, and {@see max()}.
@@ -34,7 +32,7 @@ public function average(string $q): int|float|null|string;
     /**
      * Returns the number of records.
      *
-     * @param string $q The COUNT expression. Defaults to '*'.
+     * @param string $q The `COUNT` expression. Defaults to '*'.
      *
      * @throws Exception
      * @throws InvalidConfigException