Fix phpdoc Schema classes. (#586)

src/Schema/AbstractColumnSchema.php

@@ -18,11 +18,14 @@
 use function is_resource;
 
 /**
- * The ColumnSchema class represents the metadata of a column in a database table. It provides information about the
- * column's name, type, size, precision, and other details.
+ * Represents the metadata of a column in a database table.
  *
- * The ColumnSchema class is used to store and retrieve metadata about a column in a database table. It is typically
- * used in conjunction with the TableSchema class, which represents the metadata of a database table as a whole.
+ * It provides information about the column's name, type, size, precision, and other details.
+ *
+ * The ColumnSchema class is used to store and retrieve metadata about a column in a database table.
+ *
+ * It's typically used in conjunction with the TableSchema class, which represents the metadata of a database table as a
+ * whole.
  *
  * Here is an example of how the ColumnSchema class might be used:
  *
@@ -87,8 +90,8 @@ public function dbType(string $value): void
     public function dbTypecast(mixed $value): mixed
     {
         /**
-         * the default implementation does the same as casting for PHP, but it should be possible to override this with
-         * annotation of explicit PDO type.
+         * The default implementation does the same as casting for PHP, but it should be possible to override this with
+         * annotation of an explicit PDO type.
          */
         return $this->typecast($value);
     }
@@ -236,7 +239,7 @@ public function unsigned(bool $value): void
     /**
      * Converts the input value according to {@see phpType} after retrieval from the database.
      *
-     * If the value is null or an {@see Expression}, it will not be converted.
+     * If the value is null or an {@see Expression}, it won't be converted.
      *
      * @param mixed $value The value to be converted.
      *
@@ -298,7 +301,7 @@ protected function typecast(mixed $value): mixed
                 return (int) $value;
             case SchemaInterface::PHP_TYPE_BOOLEAN:
                 /**
-                 * treating a 0 bit value as false too
+                 * Treating a 0-bit value as false too.
                  *
                  * @link https://github.com/yiisoft/yii2/issues/9006
                  */

src/Schema/AbstractColumnSchemaBuilder.php

@@ -12,8 +12,7 @@
 use function strtr;
 
 /**
- * The AbstractColumnSchemaBuilder class is a utility class that provides a convenient way to create column schemas for
- * use with Schema class @see Schema.
+ * Is a utility class that provides a convenient way to create column schemas for {@see AbstractSchema}.
  *
  * It provides methods for specifying the properties of a column, such as its type, size, default value, and whether it
  * is nullable or not. It also provides a method for creating a column schema based on the specified properties.
@@ -24,15 +23,15 @@
  * $column = (new ColumnSchemaBuilder(SchemaInterface::TYPE_INTEGER))->notNull()->defaultValue(0);
  * ```
  *
- * The AbstractColumnSchemaBuilder class provides a fluent interface, which means that the methods can be chained
- * together to create a column schema with multiple properties in a single line of code.
+ * Provides a fluent interface, which means that the methods can be chained together to create a column schema with
+ * many properties in a single line of code.
  */
 abstract class AbstractColumnSchemaBuilder implements ColumnSchemaBuilderInterface
 {
     /**
      * Internally used constants representing categories that abstract column types fall under.
      *
-     * {@see $categoryMap} for mappings of abstract column types to category.
+     * {@see $categoryMap} For mappings of abstract column types to category.
      */
     public const CATEGORY_PK = 'pk';
     public const CATEGORY_STRING = 'string';
@@ -126,8 +125,6 @@ public function comment(string|null $comment): static
 
     /**
      * Marks column as unsigned.
-     *
-     * @return static The column schema builder instance itself.
      */
     public function unsigned(): static
     {

src/Schema/AbstractSchema.php

@@ -23,10 +23,10 @@
 use function str_replace;
 
 /**
- * The AbstractSchema class provides a set of methods for working with database schemas such as creating, modifying,
- * and inspecting tables, columns, and other database objects.
+ * Provides a set of methods for working with database schemas such as creating, modifying, and inspecting tables,
+ * columns, and other database objects.
  *
- * It is a very powerful and flexible tool that allows you to perform a wide range of database operations in a
+ * It's a powerful and flexible tool that allows you to perform a wide range of database operations in a
  * database-agnostic way.
  */
 abstract class AbstractSchema implements SchemaInterface
@@ -123,7 +123,7 @@ abstract protected function loadTableUniques(string $tableName): array;
      *
      * @param string $name The table name.
      *
-     * @return TableSchemaInterface|null DBMS-dependent table metadata, `null` if the table does not exist.
+     * @return TableSchemaInterface|null DBMS-dependent table metadata, `null` if the table doesn't exist.
      */
     abstract protected function loadTableSchema(string $name): TableSchemaInterface|null;
 
@@ -213,7 +213,7 @@ public function getSchemaIndexes(string $schema = '', bool $refresh = false): ar
     }
 
     /**
-     * @throws NotSupportedException If this method is not supported by the underlying DBMS.
+     * @throws NotSupportedException If this method isn't supported by the underlying DBMS.
      *
      * @return array The schema names in the database, except system schemas.
      */
@@ -309,7 +309,7 @@ public function getTableIndexes(string $name, bool $refresh = false): array
     }
 
     /**
-     * @throws NotSupportedException If this method is not supported by the underlying DBMS.
+     * @throws NotSupportedException If this method isn't supported by the underlying DBMS.
      *
      * @return array The table names in the database.
      */
@@ -341,7 +341,7 @@ public function getTablePrimaryKey(string $name, bool $refresh = false): Constra
      * @throws InvalidCallException
      * @throws \Yiisoft\Db\Exception\InvalidArgumentException
      *
-     * @return TableSchemaInterface|null The table schema information. Null if the named table does not exist.
+     * @return TableSchemaInterface|null The table schema information. Null if the named table doesn't exist.
      */
     public function getTableSchema(string $name, bool $refresh = false): TableSchemaInterface|null
     {
@@ -425,12 +425,12 @@ public function schemaCacheEnable(bool $value): void
     /**
      * Returns all schema names in the database, including the default one but not system schemas.
      *
-     * This method should be overridden by child classes in order to support this feature because the default
+     * This method should be overridden by child classes to support this feature because the default
      * implementation simply throws an exception.
      *
-     * @throws NotSupportedException If this method is not supported by the DBMS.
+     * @throws NotSupportedException If the DBMS doesn't support this method.
      *
-     * @return array All schema names in the database, except system schemas.
+     * @return array All schemas name in the database, except system schemas.
      */
     protected function findSchemaNames(): array
     {
@@ -440,22 +440,22 @@ protected function findSchemaNames(): array
     /**
      * Returns all table names in the database.
      *
-     * This method should be overridden by child classes in order to support this feature because the default
+     * This method should be overridden by child classes to support this feature because the default
      * implementation simply throws an exception.
      *
      * @param string $schema The schema of the tables. Defaults to empty string, meaning the current or default schema.
      *
-     * @throws NotSupportedException If this method is not supported by the DBMS.
+     * @throws NotSupportedException If the DBMS doesn't support this method.
      *
-     * @return array All table names in the database. The names have NO schema name prefix.
+     * @return array All tables name in the database. The names have NO schema name prefix.
      */
     protected function findTableNames(string $schema): array
     {
         throw new NotSupportedException(static::class . ' does not support fetching all table names.');
     }
 
     /**
-     * Extracts the PHP type from abstract DB type.
+     * Extracts the PHP type from an abstract DB type.
      *
      * @param ColumnSchemaInterface $column The column schema information.
      *
@@ -537,9 +537,10 @@ protected function getSchemaMetadata(string $schema, string $type, bool $refresh
     /**
      * Returns the metadata of the given type for the given table.
      *
-     * @param string $name The table name. The table name may contain schema name if any. Do not quote the table name.
+     * @param string $name The table name. The table name may contain a schema name if any.
+     * Don't quote the table name.
      * @param string $type The metadata type.
-     * @param bool $refresh whether to reload the table metadata even if it is found in the cache.
+     * @param bool $refresh whether to reload the table metadata even if it's found in the cache.
      *
      * @throws InvalidCallException
      * @throws InvalidArgumentException
@@ -607,10 +608,10 @@ protected function getTableTypeMetadata(
     }
 
     /**
-     * Changes row's array key case to lower.
+     * Change row's array key case to lower.
      *
-     * @param array $row Thew row's array or an array of row's arrays.
-     * @param bool $multiple Whether multiple rows or a single row passed.
+     * @param array $row Thew row's array or an array of row arrays.
+     * @param bool $multiple Whether many rows or a single row passed.
      *
      * @return array The normalized row or rows.
      */
@@ -628,7 +629,7 @@ protected function normalizeRowKeyCase(array $row, bool $multiple): array
      *
      * @param string $name The table name.
      *
-     * @throws NotSupportedException If this method is not supported by the DBMS.
+     * @throws NotSupportedException If the DBMS doesn't support this method.
      *
      * @return TableSchemaInterface The with resolved table, schema, etc. names.
      *
@@ -715,7 +716,8 @@ private function saveTableMetadataToCache(string $rawName): void
     /**
      * Find the view names for the database.
      *
-     * @param string $schema the schema of the views. Defaults to empty string, meaning the current or default schema.
+     * @param string $schema The schema of the views.
+     * Defaults to empty string, meaning the current or default schema.
      *
      * @return array The names of all views in the database.
      */

src/Schema/AbstractTableSchema.php

@@ -9,7 +9,7 @@
 use function array_keys;
 
 /**
- * TableSchema represents the metadata of a database table.
+ * Represents the metadata of a database table.
  */
 abstract class AbstractTableSchema implements TableSchemaInterface
 {

src/Schema/ColumnSchemaBuilderInterface.php

@@ -5,16 +5,15 @@
 namespace Yiisoft\Db\Schema;
 
 /**
- * The ColumnSchemaBuilderInterface class is an interface that defines the methods that must be implemented by classes
- * that build the schema of a database column. It provides methods for setting the column name, type, length, precision,
- * scale, default value, and other properties of the column, as well as methods for adding constraints, such as primary
- * key, unique, and not null. Classes that implement this interface are used to create and modify the schema of a
- * database table in a database-agnostic way.
+ * This interface defines the methods that must be implemented by classes that build the schema of a database column.
+ *
+ * It provides methods for setting the column name, type, length, precision, scale, default value, and other properties
+ * of the column, as well as methods for adding constraints, such as a primary key, unique, and not null.
  */
 interface ColumnSchemaBuilderInterface
 {
     /**
-     * Specify additional SQL to be appended to column definition.
+     * Specify more SQL to be appended to column definition.
      *
      * Position modifiers will be appended after column definition in databases that support them.
      *
@@ -30,7 +29,7 @@ public function append(string $sql): self;
     public function setFormat(string $format): void;
 
     /**
-     * Builds the full string for the column's schema including type, length, default value, not null and other SQL
+     * Builds the full string for the column's schema including type, length, default value, not null and another SQL
      * fragment.
      *
      * @return string The SQL fragment that will be used for creating the column.
@@ -100,7 +99,7 @@ public function getDefault(): mixed;
 
     /**
      * @return array|int|string|null The column size or precision definition. This is what goes into the parenthesis
-     * after the column type. This can be either a string, an integer or an array. If it is an array, the array values
+     * after the column type. This can be either a string, an integer or an array. If it's an array, the array values
      * will be joined into a string separated by comma.
      */
     public function getLength(): array|int|string|null;
@@ -111,8 +110,8 @@ public function getLength(): array|int|string|null;
     public function getType(): string|null;
 
     /**
-     * @return bool|null Whether the column is or not nullable. If this is `true`, a `NOT NULL` constraint will be
-     * added. If this is `false`, a `NULL` constraint will be added.
+     * @return bool|null Whether the column is or not nullable. If this is `true`, a `NOT NULL` constraint will be added.
+     * If this is `false`, a `NULL` constraint will be added.
      */
     public function isNotNull(): bool|null;