Skip to content

Commit 2906ab9

Browse files
samdarksamdark
authored
phpdoc fixes (#604)
1 parent 19f5a06 commit 2906ab9

14 files changed

Lines changed: 161 additions & 153 deletions

‎src/Command/ParamInterface.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
namespace Yiisoft\Db\Command;
66

77
/**
8-
* This interface represents a parameter to be bound to an SQL statement.
8+
* This interface represents a parameter to bind to an SQL statement.
99
*/
1010
interface ParamInterface
1111
{

‎src/Connection/ConnectionInterface.php‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ public function beginTransaction(string $isolationLevel = null): TransactionInte
4848
/**
4949
* Create a batch query result instance.
5050
*
51-
* @param QueryInterface $query The query to be executed.
51+
* @param QueryInterface $query The query to execute.
5252
* @param bool $each Whether to return each row of the result set one at a time.
5353
*
5454
* @return BatchQueryResultInterface The batch query result instance.
@@ -58,8 +58,8 @@ public function createBatchQueryResult(QueryInterface $query, bool $each = false
5858
/**
5959
* Creates a command for execution.
6060
*
61-
* @param string|null $sql The SQL statement to be executed.
62-
* @param array $params The parameters to be bound to the SQL statement.
61+
* @param string|null $sql The SQL statement to execute.
62+
* @param array $params The parameters to bind to the SQL statement.
6363
*
6464
* @throws Exception
6565
* @throws InvalidConfigException
@@ -171,9 +171,9 @@ public function getTableSchema(string $name, bool $refresh = false): TableSchema
171171
public function getTransaction(): TransactionInterface|null;
172172

173173
/**
174-
* Returns a value indicating whether the DB connection is established.
174+
* Returns a value indicating whether the DB connection is active.
175175
*
176-
* @return bool Whether the DB connection is established.
176+
* @return bool Whether the DB connection is active.
177177
*/
178178
public function isActive(): bool;
179179

@@ -185,7 +185,7 @@ public function isSavepointEnabled(): bool;
185185
/**
186186
* Establishes a DB connection.
187187
*
188-
* It does nothing if a DB connection has already been established.
188+
* It does nothing if a DB connection is active.
189189
*
190190
* @throws Exception
191191
* @throws InvalidConfigException If connection fails.
@@ -219,8 +219,10 @@ public function setEnableSavepoint(bool $value): void;
219219
public function setProfiler(ProfilerInterface|null $profiler): void;
220220

221221
/**
222-
* The common prefix or suffix for table names. If a table name is given as `{{%TableName}}`, then the percentage
223-
* character `%` will be replaced with this property value. For example, `{{%post}}` becomes `{{tbl_post}}`.
222+
* The common prefix or suffix for table names.
223+
* If a table name is `{{%TableName}}`, then the percentage
224+
* character `%` will be replaced with this property value.
225+
* For example, `{{%post}}` becomes `{{tbl_post}}`.
224226
*
225227
* @param string $value The common prefix or suffix for table names.
226228
*/

‎src/Connection/DsnInterface.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
/**
88
* Represents a Data Source Name (DSN) that's used to configure a {@see ConnectionInterface} instance.
99
*
10-
* The DSN string format is described in {@see asString()}.
10+
* For DSN string format see {@see DsnInterface::asString()}.
1111
*/
1212
interface DsnInterface
1313
{

‎src/Constraint/ConstraintSchemaInterface.php‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,13 @@
55
namespace Yiisoft\Db\Constraint;
66

77
/**
8-
* Represents the methods that are required to work with constraints in a database, as getting the name of the
9-
* constraint, the columns that the constraint is applied to, and the type of constraint.
8+
* Defines the methods to get information about database constraints:
109
*
11-
* A constraint is a rule that's applied to the data in a table to ensure the integrity and correctness of the data.
10+
* - Name of the constraint
11+
* - Columns that the constraint applies to
12+
* - Type of constraint
13+
*
14+
* A constraint is a rule that's applied to enforce the integrity and correctness of the data.
1215
*/
1316
interface ConstraintSchemaInterface
1417
{
@@ -17,7 +20,7 @@ interface ConstraintSchemaInterface
1720
*
1821
* @param string $schema The schema of the tables. Defaults to empty string, meaning the current or default schema
1922
* name.
20-
* @param bool $refresh Whether to fetch the latest available table schemas. If this is false, cached data may be
23+
* @param bool $refresh Whether to fetch the latest available table schemas. If this is `false`, cached data may be
2124
* returned if available.
2225
*
2326
* @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
3033
*
3134
* @param string $schema The schema of the tables. Defaults to empty string, meaning the current or default schema
3235
* name.
33-
* @param bool $refresh Whether to fetch the latest available table schemas. If this is false, cached data may be
36+
* @param bool $refresh Whether to fetch the latest available table schemas. If this is `false`, cached data may be
3437
* returned if available.
3538
*
3639
* @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
4346
*
4447
* @param string $schema The schema of the tables. Defaults to empty string, meaning the current or default schema
4548
* name.
46-
* @param bool $refresh Whether to fetch the latest available table schemas. If this is false, cached data may be
49+
* @param bool $refresh Whether to fetch the latest available table schemas. If this is `false`, cached data may be
4750
* returned if available.
4851
*
4952
* @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)
8285
*
8386
* @param string $schema The schema of the tables. Defaults to empty string, meaning the current or default schema
8487
* name.
85-
* @param bool $refresh Whether to fetch the latest available table schemas. If this is false, cached data may be
88+
* @param bool $refresh Whether to fetch the latest available table schemas. If this is `false`, cached data may be
8689
* returned if available.
8790
*
8891
* @return array The unique constraints for all tables in the database. Each array element is an array of the

‎src/Driver/PDO/ConnectionPDOInterface.php‎

Lines changed: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,8 @@
1010
use Yiisoft\Db\Exception\InvalidConfigException;
1111

1212
/**
13-
* This interface defines a set of methods that must be implemented by a class to be used as a connection to a database
14-
* using {@see PDO} (PHP Data Objects).
13+
* This interface defines a set of methods to implement in a class that allows to connect to a database
14+
* with {@see PDO} (PHP Data Objects).
1515
*/
1616
interface ConnectionPDOInterface extends ConnectionInterface
1717
{
@@ -32,7 +32,8 @@ public function getActivePDO(string $sql = '', bool $forRead = null): PDO|null;
3232
*
3333
* This property is mainly managed by {@see open()} and {@see close()} methods.
3434
*
35-
* When a DB connection is active, this property will represent a PDO instance; otherwise, it will be null.
35+
* When a DB connection is active, this property will represent a PDO instance.
36+
* Otherwise, it will be `null`.
3637
*
3738
* @return PDO|null The PHP PDO instance associated with this DB connection.
3839
*
@@ -43,26 +44,28 @@ public function getPDO(): PDO|null;
4344
/**
4445
* Returns current DB driver.
4546
*
46-
* @return PDODriverInterface - The driver used to create current connection.
47+
* @return PDODriverInterface The driver used to create current connection.
4748
*/
4849
public function getDriver(): PDODriverInterface;
4950

5051
/**
51-
* Return emulate prepare value.
52+
* Whether to emulate prepared statements on PHP side.
53+
*
54+
* @see setEmulatePrepare()
5255
*/
5356
public function getEmulatePrepare(): bool|null;
5457

5558
/**
56-
* Whether to turn on prepare emulation.
59+
* Whether to turn on prepare statements emulation on PHP side.
5760
*
58-
* Defaults to false, meaning {@see PDO} will use native-prepared support if available.
61+
* Defaults to `false`, meaning {@see PDO} will use database prepared statements support if possible.
5962
*
60-
* For some databases (such as MySQL), this may need to be set true so that {@see PDO} can emulate to preparing
61-
* support to bypassing the buggy native prepare support.
63+
* For some databases (such as MySQL), you may need to set it to `true` so that {@see PDO} can
64+
* replace buggy prepared statements support provided by database itself.
6265
*
63-
* The default value is null, which means the {@see PDO} `ATTR_EMULATE_PREPARES` value won't be changed.
66+
* The default value is `null`, which means using default {@see PDO} `ATTR_EMULATE_PREPARES` value.
6467
*
65-
* @param bool $value Whether to turn on prepare emulation.
68+
* @param bool $value Whether to turn on prepared statement emulation.
6669
*/
6770
public function setEmulatePrepare(bool $value): void;
6871
}

‎src/Driver/PDO/PDODriverInterface.php‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -8,20 +8,20 @@
88
use Yiisoft\Db\Driver\DriverInterface;
99

1010
/**
11-
* This interface provides a set of methods that must be implemented by {@see PDO} (PHP Data Objects) driver classes.
11+
* This interface provides a set of methods to implement by {@see PDO} (PHP Data Objects) driver classes.
1212
*
1313
* @link https://www.php.net/manual/en/book.pdo.php
1414
*/
1515
interface PDODriverInterface extends DriverInterface
1616
{
1717
/**
18-
* Set {@see PDO} attributes (name => value) that should be set when calling {@see open()} to establish a DB
18+
* Set {@see PDO} attributes (name => value) to set when calling {@see open()} to establish a DB
1919
* connection.
2020
*
2121
* Please refer to the [PHP manual](https://php.net/manual/en/pdo.setattribute.php) for details about available
2222
* attributes.
2323
*
24-
* @param array $attributes The attributes (name => value) to be set on the DB connection.
24+
* @param array $attributes The attributes (name => value) to set on the DB connection.
2525
*/
2626
public function attributes(array $attributes): void;
2727

@@ -34,21 +34,22 @@ public function createConnection(): PDO;
3434

3535
/**
3636
* Set charset used for database connection. The property is only used for MySQL, PostgresSQL databases. Defaults to
37-
* null, meaning using default charset as configured by the database.
37+
* `null`, meaning using default charset as configured by the database.
3838
*
3939
* For Oracle Database, the charset must be specified in the {@see dsn}, for example, for UTF-8 by appending
4040
* `;charset=UTF-8` to the DSN string.
4141
*
42-
* The same applies for if you're using GBK or BIG5 charset with MySQL, then it's highly recommended specifying
42+
* The same applies if you're using GBK or BIG5 charset with MySQL.
43+
* In this case it's highly recommended specifying
4344
* charset via {@see dsn} like `'mysql:dbname=database;host=127.0.0.1;charset=GBK;'`.
4445
*
45-
* @param string|null $charset The charset to be used for database connection.
46+
* @param string|null $charset The charset to use for database connection.
4647
*/
4748
public function charset(string|null $charset): void;
4849

4950
/**
50-
* @return string|null The charset of the pdo instance. Null is returned if the charset isn't set yet or not
51-
* supported by the pdo driver
51+
* @return string|null The charset of the pdo instance. If the charset isn't set yet or not
52+
* supported by the PDO driver, it returns `null`.
5253
*/
5354
public function getCharset(): string|null;
5455

@@ -73,14 +74,14 @@ public function getPassword(): string;
7374
public function getUsername(): string;
7475

7576
/**
76-
* Set password for establishing DB connection. Defaults to `null` meaning no password to use.
77+
* Set password for establishing DB connection. Defaults to `null` meaning use no password.
7778
*
7879
* @param string $password The password for establishing DB connection.
7980
*/
8081
public function password(string $password): void;
8182

8283
/**
83-
* Set username for establishing DB connection. Defaults to `null` meaning no username to use.
84+
* Set username for establishing DB connection. Defaults to `null` meaning use no username.
8485
*
8586
* @param string $username The username for establishing DB connection.
8687
*/

‎src/Expression/ExpressionBuilderInterface.php‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,12 @@
66

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

‎src/Expression/ExpressionInterface.php‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,12 @@
55
namespace Yiisoft\Db\Expression;
66

77
/**
8-
* This interface defines a set of methods that an object should implement to be used as an expression in database
9-
* queries, such as for filtering or ordering results.
8+
* This interface defines a set of methods that an object should implement to represent an expression in database
9+
* queries, such as one for filtering or ordering results.
1010
*
1111
* These methods include getting the expression as a string, getting the parameters to bind to the expression, and
12-
* getting the types of the parameters. Classes that implement this interface can be used in a variety of query building
12+
* getting the types of the parameters.
13+
* You can use classes that implement this interface in a variety of query building
1314
* methods provided by the library.
1415
*
1516
* The database abstraction layer of a Yii framework supports objects that implement this interface and will use

‎src/Profiler/ContextInterface.php‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,13 @@
44

55
namespace Yiisoft\Db\Profiler;
66

7+
/**
8+
* Profiling context.
9+
*/
710
interface ContextInterface
811
{
912
/**
10-
* @return string Type of the context
13+
* @return string Type of the context.
1114
*/
1215
public function getType(): string;
1316

‎src/Profiler/ProfilerInterface.php‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
namespace Yiisoft\Db\Profiler;
66

77
/**
8-
* Interface-decorator for work with `yiisoft\profiler` or another profiler.
8+
* Interface-decorator to work with `yiisoft\profiler` or another profiler.
99
*
1010
* @see \Yiisoft\Db\Connection\ConnectionInterface::setProfiler()
1111
*/
@@ -14,9 +14,9 @@ interface ProfilerInterface
1414
/**
1515
* Marks the beginning of a code block for profiling.
1616
*
17-
* This has to be matched with a call to {@see end()} with the same category name.
17+
* There should be a matching call to {@see end()} with the same category name.
1818
*
19-
* The begin and end calls must also be nested.
19+
* The `begin()` and `end()` calls must also be properly nested.
2020
*
2121
* @param string $token Token for the code block.
2222
* @param array|ContextInterface $context The context data of this profile block.
@@ -26,7 +26,9 @@ public function begin(string $token, array|ContextInterface $context = []): void
2626
/**
2727
* Marks the end of a code block for profiling.
2828
*
29-
* This has to be matched with an earlier call to {@see begin()} with the same category name.
29+
* There should be a matching call to {@see begin()} with the same category name.
30+
*
31+
* The `begin()` and `end()` calls must also be properly nested.
3032
*
3133
* @param string $token Token for the code block.
3234
* @param array|ContextInterface $context The context data of this profile block.

0 commit comments

Comments
 (0)