cs, improved phpDoc

src/Database/Connection.php

@@ -16,7 +16,7 @@
 
 
 /**
- * Represents a connection between PHP and a database server.
+ * Manages database connection and executes SQL queries.
  */
 class Connection
 {
@@ -52,6 +52,9 @@ public function __construct(
 	}
 
 
+	/**
+	 * @throws ConnectionException
+	 */
 	public function connect(): void
 	{
 		if ($this->pdo) {
@@ -74,13 +77,19 @@ public function connect(): void
 	}
 
 
+	/**
+	 * Disconnects and connects to database again.
+	 */
 	public function reconnect(): void
 	{
 		$this->disconnect();
 		$this->connect();
 	}
 
 
+	/**
+	 * Disconnects from database.
+	 */
 	public function disconnect(): void
 	{
 		$this->pdo = null;
@@ -121,13 +130,19 @@ public function getReflection(): Reflection
 	}
 
 
+	/**
+	 * Sets callback for row preprocessing.
+	 */
 	public function setRowNormalizer(?callable $normalizer): static
 	{
 		$this->rowNormalizer = $normalizer;
 		return $this;
 	}
 
 
+	/**
+	 * Returns last inserted ID.
+	 */
 	public function getInsertId(?string $sequence = null): string
 	{
 		try {
@@ -139,6 +154,9 @@ public function getInsertId(?string $sequence = null): string
 	}
 
 
+	/**
+	 * Quotes string for use in SQL.
+	 */
 	public function quote(string $string, int $type = PDO::PARAM_STR): string
 	{
 		try {
@@ -149,6 +167,10 @@ public function quote(string $string, int $type = PDO::PARAM_STR): string
 	}
 
 
+	/**
+	 * Starts a transaction.
+	 * @throws \LogicException  when called inside a transaction
+	 */
 	public function beginTransaction(): void
 	{
 		if ($this->transactionDepth !== 0) {
@@ -159,6 +181,10 @@ public function beginTransaction(): void
 	}
 
 
+	/**
+	 * Commits current transaction.
+	 * @throws \LogicException  when called inside a transaction
+	 */
 	public function commit(): void
 	{
 		if ($this->transactionDepth !== 0) {
@@ -169,6 +195,10 @@ public function commit(): void
 	}
 
 
+	/**
+	 * Rolls back current transaction.
+	 * @throws \LogicException  when called inside a transaction
+	 */
 	public function rollBack(): void
 	{
 		if ($this->transactionDepth !== 0) {
@@ -179,6 +209,9 @@ public function rollBack(): void
 	}
 
 
+	/**
+	 * Executes callback inside a transaction.
+	 */
 	public function transaction(callable $callback): mixed
 	{
 		if ($this->transactionDepth === 0) {
@@ -324,6 +357,9 @@ public function fetchAll(#[Language('SQL')] string $sql, #[Language('GenericSQL'
 	}
 
 
+	/**
+	 * Creates SQL literal value.
+	 */
 	public static function literal(string $value, ...$params): SqlLiteral
 	{
 		return new SqlLiteral($value, $params);

src/Database/Conventions.php

@@ -12,6 +12,9 @@
 use Nette\Database\Conventions\AmbiguousReferenceKeyException;
 
 
+/**
+ * Provides naming conventions for database tables and columns.
+ */
 interface Conventions
 {
 	/**

src/Database/Conventions/DiscoveredConventions.php

@@ -14,7 +14,7 @@
 
 
 /**
- * Conventions based on database structure.
+ * Discovers database conventions based on table structure metadata.
  */
 class DiscoveredConventions implements Conventions
 {

src/Database/Conventions/StaticConventions.php

@@ -13,7 +13,7 @@
 
 
 /**
- * Conventions based on static definition.
+ * Defines naming conventions for database structure using static patterns.
  */
 class StaticConventions implements Conventions
 {

src/Database/Driver.php

@@ -11,15 +11,15 @@
 
 
 /**
- * Supplemental PDO database driver.
+ * Provides database-specific functionality.
  */
 interface Driver
 {
 	public const
 		SupportSequence = 'sequence',
 		SupportSelectUngroupedColumns = 'ungrouped_cols',
 		SupportMultiInsertAsSelect = 'insert_as_select',
-		SupportMultiColumnAsOrCond = 'multi_column_as_or',
+		SupportMultiColumnAsOrCondition = 'multi_column_as_or',
 		SupportSubselect = 'subselect',
 		SupportSchema = 'schema';
 
@@ -32,6 +32,12 @@ interface Driver
 		SUPPORT_SUBSELECT = 'subselect',
 		SUPPORT_SCHEMA = 'schema';
 
+	/**
+	 * Checks if the engine supports a specific feature.
+	 * @param  self::Support*  $feature
+	 */
+	function isSupported(string $feature): bool;
+
 	/**
 	 * Initializes connection.
 	 */
@@ -42,56 +48,54 @@ function initialize(Connection $connection, array $options): void;
 	 */
 	function convertException(\PDOException $e): DriverException;
 
-	/**
-	 * Delimites identifier for use in a SQL statement.
-	 */
+	/********************* SQL utilities ****************d*g**/
+
+	/** Adds delimiters around database identifier. */
 	function delimite(string $name): string;
 
-	/**
-	 * Formats date-time for use in a SQL statement.
-	 */
+	/** Formats a date-time value for use in an SQL statement. */
 	function formatDateTime(\DateTimeInterface $value): string;
 
-	/**
-	 * Formats date-time interval for use in a SQL statement.
-	 */
+	/** Formats a date-time interval for use in an SQL statement. */
 	function formatDateInterval(\DateInterval $value): string;
 
-	/**
-	 * Encodes string for use in a LIKE statement.
-	 */
+	/** Encodes string for use in a LIKE statement. */
 	function formatLike(string $value, int $pos): string;
 
-	/**
-	 * Injects LIMIT/OFFSET to the SQL query.
-	 */
+	/** Applies LIMIT and OFFSET clauses to an SQL query. */
 	function applyLimit(string &$sql, ?int $limit, ?int $offset): void;
 
 	/********************* reflection ****************d*g**/
 
-	/** @return list<array{name: string, fullName: string, view: bool}> */
+	/**
+	 * Returns a list of all tables in the database.
+	 * @return list<array{name: string, fullName: string, view: bool}>
+	 */
 	function getTables(): array;
 
-	/** @return list<array{name: string, table: string, nativetype: string, size: int|null, nullable: bool, default: mixed, autoincrement: bool, primary: bool, vendor: array}> */
+	/**
+	 * Returns metadata for all columns in a table.
+	 * @return list<array{name: string, table: string, nativetype: string, size: int|null, nullable: bool, default: mixed, autoincrement: bool, primary: bool, vendor: array}>
+	 */
 	function getColumns(string $table): array;
 
-	/** @return list<array{name: string, columns: list<string>, unique: bool, primary: bool}> */
+	/**
+	 * Returns metadata for all indexes in a table.
+	 * @return list<array{name: string, columns: list<string>, unique: bool, primary: bool}>
+	 */
 	function getIndexes(string $table): array;
 
-	/** @return list<array{name: string, local: string, table: string, foreign: string}> */
+	/**
+	 * Returns metadata for all foreign keys in a table.
+	 * @return list<array{name: string, local: string, table: string, foreign: string}>
+	 */
 	function getForeignKeys(string $table): array;
 
 	/**
 	 * Returns associative array of detected types (IStructure::FIELD_*) in result set.
 	 * @return array<string, string>
 	 */
 	function getColumnTypes(\PDOStatement $statement): array;
-
-	/**
-	 * Cheks if driver supports specific property
-	 * @param  self::Support*  $item
-	 */
-	function isSupported(string $item): bool;
 }
 
 

src/Database/Drivers/MsSqlDriver.php

@@ -26,6 +26,12 @@ public function initialize(Nette\Database\Connection $connection, array $options
 	}
 
 
+	public function isSupported(string $feature): bool
+	{
+		return $feature === self::SupportSubselect;
+	}
+
+
 	public function convertException(\PDOException $e): Nette\Database\DriverException
 	{
 		return Nette\Database\DriverException::from($e);
@@ -216,10 +222,4 @@ public function getColumnTypes(\PDOStatement $statement): array
 	{
 		return Nette\Database\Helpers::detectTypes($statement);
 	}
-
-
-	public function isSupported(string $item): bool
-	{
-		return $item === self::SupportSubselect;
-	}
 }

src/Database/Drivers/MySqlDriver.php

@@ -48,6 +48,16 @@ public function initialize(Nette\Database\Connection $connection, array $options
 	}
 
 
+	public function isSupported(string $feature): bool
+	{
+		// MULTI_COLUMN_AS_OR_COND due to mysql bugs:
+		// - http://bugs.mysql.com/bug.php?id=31188
+		// - http://bugs.mysql.com/bug.php?id=35819
+		// and more.
+		return $feature === self::SupportSelectUngroupedColumns || $feature === self::SupportMultiColumnAsOrCondition;
+	}
+
+
 	public function convertException(\PDOException $e): Nette\Database\DriverException
 	{
 		$code = $e->errorInfo[1] ?? null;
@@ -211,14 +221,4 @@ public function getColumnTypes(\PDOStatement $statement): array
 
 		return $types;
 	}
-
-
-	public function isSupported(string $item): bool
-	{
-		// MULTI_COLUMN_AS_OR_COND due to mysql bugs:
-		// - http://bugs.mysql.com/bug.php?id=31188
-		// - http://bugs.mysql.com/bug.php?id=35819
-		// and more.
-		return $item === self::SupportSelectUngroupedColumns || $item === self::SupportMultiColumnAsOrCond;
-	}
 }

src/Database/Drivers/OciDriver.php

@@ -28,6 +28,12 @@ public function initialize(Nette\Database\Connection $connection, array $options
 	}
 
 
+	public function isSupported(string $feature): bool
+	{
+		return $feature === self::SupportSequence || $feature === self::SupportSubselect;
+	}
+
+
 	public function convertException(\PDOException $e): Nette\Database\DriverException
 	{
 		$code = $e->errorInfo[1] ?? null;
@@ -133,10 +139,4 @@ public function getColumnTypes(\PDOStatement $statement): array
 	{
 		return [];
 	}
-
-
-	public function isSupported(string $item): bool
-	{
-		return $item === self::SupportSequence || $item === self::SupportSubselect;
-	}
 }

src/Database/Drivers/OdbcDriver.php

@@ -22,6 +22,12 @@ public function initialize(Nette\Database\Connection $connection, array $options
 	}
 
 
+	public function isSupported(string $feature): bool
+	{
+		return $feature === self::SupportSubselect;
+	}
+
+
 	public function convertException(\PDOException $e): Nette\Database\DriverException
 	{
 		return Nette\Database\DriverException::from($e);
@@ -104,10 +110,4 @@ public function getColumnTypes(\PDOStatement $statement): array
 	{
 		return [];
 	}
-
-
-	public function isSupported(string $item): bool
-	{
-		return $item === self::SupportSubselect;
-	}
 }

src/Database/Drivers/PgSqlDriver.php

@@ -26,6 +26,12 @@ public function initialize(Nette\Database\Connection $connection, array $options
 	}
 
 
+	public function isSupported(string $feature): bool
+	{
+		return $feature === self::SupportSequence || $feature === self::SupportSubselect || $feature === self::SupportSchema;
+	}
+
+
 	public function convertException(\PDOException $e): Nette\Database\DriverException
 	{
 		$code = $e->errorInfo[0] ?? null;
@@ -244,12 +250,6 @@ public function getColumnTypes(\PDOStatement $statement): array
 	}
 
 
-	public function isSupported(string $item): bool
-	{
-		return $item === self::SupportSequence || $item === self::SupportSubselect || $item === self::SupportSchema;
-	}
-
-
 	/**
 	 * Converts: schema.name => "schema"."name"
 	 */