Remove unnecessary comments from Part classes, keep only type annotations

simon-mundy · simon-mundy · commit 7a59c3d1b07f · 2026-02-28T19:23:38.000+11:00
Signed-off-by: Simon Mundy &lt;simon.mundy@peptolab.com&gt;
diff --git a/src/Sql/Part/Columns.php b/src/Sql/Part/Columns.php
@@ -16,29 +16,14 @@
 use function is_string;
 use function key;
 
-/**
- * Holds column definitions and renders the column list for SELECT statements.
- * Includes both main table columns and join columns.
- *
- * Columns are normalized to ColumnRef[] at set time. Rendering is inlined
- * with instanceof fast-paths for Identifier (hot path) and Literal (star).
- */
 class Columns extends AbstractPart
 {
-    /** @var ColumnRef[] Normalized column references */
+    /** @var ColumnRef[] */
     private array $columnRefs = [];
-
-    /** @var array Raw columns for getRawState() backward compatibility */
     private array $rawColumns = [Select::SQL_STAR];
-
     private bool $prefixColumnsWithTable = true;
-
-    /**
-     * Set during preparePartsForBuild -- the resolved table prefix (e.g. "table".)
-     */
     private string $fromTablePrefix = '';
-
-    /** @var JoinSpec[] Join specs for column resolution */
+    /** @var JoinSpec[] */
     private array $joinSpecs = [];
 
     public function __construct()
@@ -149,9 +134,6 @@ public function add(array|ExpressionInterface|string $column, ?string $alias = n
         return $this;
     }
 
-    /**
-     * Reconstruct the original format for getRawState() compatibility.
-     */
     public function get(): array
     {
         return $this->rawColumns;
@@ -168,29 +150,19 @@ public function getPrefixColumnsWithTable(): bool
         return $this->prefixColumnsWithTable;
     }
 
-    /**
-     * Set the table prefix for column resolution (e.g. "table".)
-     */
     public function setFromTablePrefix(string $prefix): static
     {
         $this->fromTablePrefix = $prefix;
         return $this;
     }
 
-    /**
-     * Set join specs for column resolution during rendering.
-     *
-     * @param JoinSpec[] $specs
-     */
+    /** @param JoinSpec[] $specs */
     public function setJoinSpecs(array $specs): static
     {
         $this->joinSpecs = $specs;
         return $this;
     }
 
-    /**
-     * Normalize the raw columns array into ColumnRef[].
-     */
     private function normalizeColumns(): void
     {
         $this->columnRefs = [];
diff --git a/src/Sql/Part/Combine.php b/src/Sql/Part/Combine.php
@@ -6,9 +6,6 @@
 
 use PhpDb\Sql\Select;
 
-/**
- * Holds and renders UNION/EXCEPT/INTERSECT clause for SELECT statements.
- */
 class Combine extends AbstractPart
 {
     private array $combine = [];
diff --git a/src/Sql/Part/From.php b/src/Sql/Part/From.php
@@ -7,11 +7,6 @@
 use PhpDb\Sql\Select;
 use PhpDb\Sql\TableIdentifier;
 
-/**
- * Holds and renders a table reference with optional alias.
- * Used by Select (FROM), Insert (INTO), Update (UPDATE), Delete (DELETE FROM).
- * Normalizes input to TableRef at set time — alias extraction happens once, not at render time.
- */
 class From extends AbstractPart
 {
     private ?TableRef $ref = null;
@@ -56,9 +51,6 @@ public function set(string|array|TableIdentifier|Select|null $table): static
         return $this;
     }
 
-    /**
-     * Reconstruct the original format for getRawState() compatibility.
-     */
     public function get(): string|array|TableIdentifier|Select|null
     {
         if ($this->ref === null) {
@@ -72,10 +64,6 @@ public function get(): string|array|TableIdentifier|Select|null
         return $this->ref->table;
     }
 
-    /**
-     * Get the quoted table prefix for column prefixing (e.g. "table".)
-     * Returns the alias if one is set, otherwise the table name.
-     */
     public function getQuotedPrefix(SqlProcessor $processor): string
     {
         if ($this->ref === null) {
diff --git a/src/Sql/Part/GroupBy.php b/src/Sql/Part/GroupBy.php
@@ -11,10 +11,6 @@
 use function is_array;
 use function is_string;
 
-/**
- * Holds and renders GROUP BY clause.
- * Normalizes columns to ColumnRef at add time.
- */
 class GroupBy extends AbstractPart
 {
     /** @var ColumnRef[]|null */
@@ -60,9 +56,6 @@ public function add(mixed $group): static
         return $this;
     }
 
-    /**
-     * Reconstruct the original format for getRawState() compatibility.
-     */
     public function get(): ?array
     {
         if ($this->group === null) {
diff --git a/src/Sql/Part/Having.php b/src/Sql/Part/Having.php
@@ -9,9 +9,6 @@
 use PhpDb\Sql\Predicate\PredicateInterface;
 use PhpDb\Sql\Predicate\PredicateSet;
 
-/**
- * Wraps a Having predicate model and renders it as a HAVING clause.
- */
 class Having extends AbstractPart
 {
     public ?HavingModel $model = null;
@@ -30,9 +27,6 @@ public function isEmpty(): bool
         return $this->model === null || $this->model->count() === 0;
     }
 
-    /**
-     * Add predicates to the having clause, or replace with a Having instance.
-     */
     public function addPredicates(
         PredicateInterface|HavingModel|array|Closure|string $predicate,
         string $combination = PredicateSet::OP_AND
diff --git a/src/Sql/Part/InsertColumnValue.php b/src/Sql/Part/InsertColumnValue.php
@@ -6,10 +6,6 @@
 
 use PhpDb\Sql\ArgumentInterface;
 
-/**
- * Normalized INSERT column=value pair.
- * The value is stored as an ArgumentInterface (Parameter for scalars, Select for expressions/subqueries).
- */
 final readonly class InsertColumnValue
 {
     public function __construct(
diff --git a/src/Sql/Part/InsertSelect.php b/src/Sql/Part/InsertSelect.php
@@ -9,17 +9,13 @@
 use function array_keys;
 use function implode;
 
-/**
- * Renders an INSERT INTO table (columns) SELECT ... statement.
- * Mutually exclusive with InsertValues -- only one renders.
- */
 class InsertSelect extends AbstractPart
 {
     private string $keyword = 'INSERT INTO';
     private From $table;
     private ?Select $select = null;
 
-    /** @var array<string, mixed> Column names (keys) from the columns array */
+    /** @var array<string, mixed> */
     private array $columns = [];
 
     public function __construct(From $table)
diff --git a/src/Sql/Part/InsertValues.php b/src/Sql/Part/InsertValues.php
@@ -16,17 +16,12 @@
 
 use function implode;
 
-/**
- * Renders an INSERT INTO table (columns) VALUES (values) statement.
- * Mutually exclusive with InsertSelect -- only one renders.
- * Normalizes values to ArgumentInterface at setColumns time.
- */
 class InsertValues extends AbstractPart
 {
     private string $keyword = 'INSERT INTO';
     private From $table;
 
-    /** @var InsertColumnValue[] Normalized column-value pairs */
+    /** @var InsertColumnValue[] */
     private array $columnValues = [];
 
     private bool $hasSelect = false;
@@ -87,11 +82,7 @@ public function getKeyword(): string
         return $this->keyword;
     }
 
-    /**
-     * Set columns with values, normalizing to InsertColumnValue[].
-     *
-     * @param array<string, mixed> $columns Column-to-value mapping
-     */
+    /** @param array<string, mixed> $columns */
     public function setColumns(array $columns): void
     {
         $this->columnValues = [];
@@ -100,9 +91,6 @@ public function setColumns(array $columns): void
         }
     }
 
-    /**
-     * Reconstruct the raw column-to-value mapping for compatibility.
-     */
     public function getColumns(): array
     {
         $result = [];
@@ -117,9 +105,6 @@ public function setHasSelect(bool $hasSelect): void
         $this->hasSelect = $hasSelect;
     }
 
-    /**
-     * Normalize a raw value to an ArgumentInterface.
-     */
     private function normalizeValue(string $column, mixed $value): ArgumentInterface
     {
         if ($value instanceof ArgumentInterface) {
@@ -138,7 +123,6 @@ private function normalizeValue(string $column, mixed $value): ArgumentInterface
             return new Literal('NULL');
         }
 
-        // Scalar — bind as parameter
         return new Parameter($value, preferredName: $column);
     }
 }
diff --git a/src/Sql/Part/JoinSpec.php b/src/Sql/Part/JoinSpec.php
@@ -18,11 +18,6 @@
 use function key;
 use function sprintf;
 
-/**
- * Normalized join specification.
- * All type discrimination (array alias, table type, expression ON)
- * happens at construction time.
- */
 final readonly class JoinSpec
 {
     public string|TableIdentifier|Select|ExpressionInterface $table;
@@ -32,7 +27,7 @@
     public bool $isExpressionOn;
     public string $type;
 
-    /** @var ColumnRef[] Pre-normalized column references */
+    /** @var ColumnRef[] */
     public array $columnRefs;
 
     /** @param array{name: array|string|TableIdentifier, on: PredicateInterface|string, columns: array, type: string} $join */
diff --git a/src/Sql/Part/JoinTableType.php b/src/Sql/Part/JoinTableType.php
@@ -4,11 +4,6 @@
 
 namespace PhpDb\Sql\Part;
 
-/**
- * Discriminator for join table variants.
- * Set at JoinSpec construction time so the render loop uses a match
- * instead of an instanceof chain.
- */
 enum JoinTableType
 {
     case Expression;
diff --git a/src/Sql/Part/Joins.php b/src/Sql/Part/Joins.php
@@ -18,23 +18,16 @@
 use function preg_replace_callback;
 use function spl_object_id;
 
-/**
- * Wraps a Join model and renders all JOIN clauses.
- * Used by Select and Update.
- *
- * JoinSpecs are normalized at join() time. The rendering loop uses typed access
- * on JoinSpec — no instanceof/is_array cascades or per-render allocations.
- */
 class Joins extends AbstractPart
 {
     private const IDENTIFIER_PATTERN = '/\b(?!(?:AS|AND|OR|BETWEEN)\b)([a-zA-Z_]\w*+(?:\.[a-zA-Z_]\w*+)*)(?!\s*\()/i';
 
     public ?Join $model = null;
 
-    /** @var JoinSpec[] Normalized join specifications, built at join() time */
+    /** @var JoinSpec[] */
     private array $specs = [];
 
-    /** @var array[] Raw join data for lazy Join model building */
+    /** @var array[] */
     private array $rawJoins = [];
 
     private ?string $sqlCache = null;
@@ -107,9 +100,6 @@ public function getSpecs(): array
         return $this->specs;
     }
 
-    /**
-     * Add a join specification.
-     */
     public function join(
         array|string|TableIdentifier $name,
         PredicateInterface|string $on,
diff --git a/src/Sql/Part/Limit.php b/src/Sql/Part/Limit.php
@@ -7,10 +7,6 @@
 use PhpDb\Adapter\ParameterContainer;
 use PhpDb\Sql\Argument\Parameter;
 
-/**
- * Holds and renders LIMIT clause.
- * Normalizes limit value to Parameter at set time.
- */
 class Limit extends AbstractPart
 {
     private ?Parameter $limit = null;
diff --git a/src/Sql/Part/Offset.php b/src/Sql/Part/Offset.php
@@ -7,10 +7,6 @@
 use PhpDb\Adapter\ParameterContainer;
 use PhpDb\Sql\Argument\Parameter;
 
-/**
- * Holds and renders OFFSET clause.
- * Normalizes offset value to Parameter at set time.
- */
 class Offset extends AbstractPart
 {
     private ?Parameter $offset = null;
diff --git a/src/Sql/Part/OrderBy.php b/src/Sql/Part/OrderBy.php
@@ -13,10 +13,6 @@
 use function preg_split;
 use function str_contains;
 
-/**
- * Holds and renders ORDER BY clause.
- * Normalizes order specs to OrderSpec at add time.
- */
 class OrderBy extends AbstractPart
 {
     final public const ORDER_ASCENDING  = 'ASC';
@@ -66,24 +62,17 @@ public function add(ExpressionInterface|array|string $order): static
             if ($v instanceof ExpressionInterface) {
                 $this->order[] = new OrderSpec($v);
             } elseif (is_string($k)) {
-                // ['column' => 'DESC']
                 $this->order[] = new OrderSpec($k, $v);
             } elseif (str_contains($v, ' ')) {
-                // 'column DESC'
                 [$col, $dir]   = explode(' ', $v, 2);
                 $this->order[] = new OrderSpec($col, $dir);
             } else {
-                // 'column' (no direction)
                 $this->order[] = new OrderSpec($v);
             }
         }
         return $this;
     }
 
-    /**
-     * Reconstruct the order as 'column DIRECTION' strings for getRawState() compatibility.
-     * Expressions are returned at integer keys.
-     */
     public function get(): array
     {
         $result = [];
diff --git a/src/Sql/Part/PartInterface.php b/src/Sql/Part/PartInterface.php
@@ -8,14 +8,7 @@
 
 interface PartInterface extends Stringable
 {
-    /**
-     * Render this part to a SQL string fragment.
-     * Returns null if this part should be omitted from the final statement.
-     */
     public function toSql(SqlProcessor $processor): ?string;
 
-    /**
-     * Whether this part currently has no content to render.
-     */
     public function isEmpty(): bool;
 }
diff --git a/src/Sql/Part/Quantifier.php b/src/Sql/Part/Quantifier.php
diff --git a/src/Sql/Part/Set.php b/src/Sql/Part/Set.php
diff --git a/src/Sql/Part/SetValue.php b/src/Sql/Part/SetValue.php
diff --git a/src/Sql/Part/Table.php b/src/Sql/Part/Table.php
diff --git a/src/Sql/Part/TableRef.php b/src/Sql/Part/TableRef.php
diff --git a/src/Sql/Part/Where.php b/src/Sql/Part/Where.php

Original file line number	Diff line number	Diff line change
`@@ -6,9 +6,6 @@`
`6`	`6`
`7`	`7`	`use PhpDb\Sql\Select;`
`8`	`8`
`9`		`-/**`
`10`		`- * Holds and renders UNION/EXCEPT/INTERSECT clause for SELECT statements.`
`11`		`- */`
`12`	`9`	`class Combine extends AbstractPart`
`13`	`10`	`{`
`14`	`11`	`private array $combine = [];`
Original file line number	Diff line number	Diff line change
`@@ -7,11 +7,6 @@`
`7`	`7`	`use PhpDb\Sql\Select;`
`8`	`8`	`use PhpDb\Sql\TableIdentifier;`
`9`	`9`
`10`		`-/**`
`11`		`- * Holds and renders a table reference with optional alias.`
`12`		`- * Used by Select (FROM), Insert (INTO), Update (UPDATE), Delete (DELETE FROM).`
`13`		`- * Normalizes input to TableRef at set time — alias extraction happens once, not at render time.`
`14`		`- */`
`15`	`10`	`class From extends AbstractPart`
`16`	`11`	`{`
`17`	`12`	`private ?TableRef $ref = null;`
`@@ -56,9 +51,6 @@ public function set(string\|array\|TableIdentifier\|Select\|null $table): static`
`56`	`51`	`return $this;`
`57`	`52`	`}`
`58`	`53`
`59`		`- /**`
`60`		`- * Reconstruct the original format for getRawState() compatibility.`
`61`		`- */`
`62`	`54`	`public function get(): string\|array\|TableIdentifier\|Select\|null`
`63`	`55`	`{`
`64`	`56`	`if ($this->ref === null) {`
`@@ -72,10 +64,6 @@ public function get(): string\|array\|TableIdentifier\|Select\|null`
`72`	`64`	`return $this->ref->table;`
`73`	`65`	`}`
`74`	`66`
`75`		`- /**`
`76`		`- * Get the quoted table prefix for column prefixing (e.g. "table".)`
`77`		`- * Returns the alias if one is set, otherwise the table name.`
`78`		`- */`
`79`	`67`	`public function getQuotedPrefix(SqlProcessor $processor): string`
`80`	`68`	`{`
`81`	`69`	`if ($this->ref === null) {`
Original file line number	Diff line number	Diff line change
`@@ -11,10 +11,6 @@`
`11`	`11`	`use function is_array;`
`12`	`12`	`use function is_string;`
`13`	`13`
`14`		`-/**`
`15`		`- * Holds and renders GROUP BY clause.`
`16`		`- * Normalizes columns to ColumnRef at add time.`
`17`		`- */`
`18`	`14`	`class GroupBy extends AbstractPart`
`19`	`15`	`{`
`20`	`16`	`/** @var ColumnRef[]\|null */`
`@@ -60,9 +56,6 @@ public function add(mixed $group): static`
`60`	`56`	`return $this;`
`61`	`57`	`}`
`62`	`58`
`63`		`- /**`
`64`		`- * Reconstruct the original format for getRawState() compatibility.`
`65`		`- */`
`66`	`59`	`public function get(): ?array`
`67`	`60`	`{`
`68`	`61`	`if ($this->group === null) {`
Original file line number	Diff line number	Diff line change
`@@ -6,10 +6,6 @@`
`6`	`6`
`7`	`7`	`use PhpDb\Sql\ArgumentInterface;`
`8`	`8`
`9`		`-/**`
`10`		`- * Normalized INSERT column=value pair.`
`11`		`- * The value is stored as an ArgumentInterface (Parameter for scalars, Select for expressions/subqueries).`
`12`		`- */`
`13`	`9`	`final readonly class InsertColumnValue`
`14`	`10`	`{`
`15`	`11`	`public function __construct(`
Original file line number	Diff line number	Diff line change
`@@ -16,17 +16,12 @@`
`16`	`16`
`17`	`17`	`use function implode;`
`18`	`18`
`19`		`-/**`
`20`		`- * Renders an INSERT INTO table (columns) VALUES (values) statement.`
`21`		`- * Mutually exclusive with InsertSelect -- only one renders.`
`22`		`- * Normalizes values to ArgumentInterface at setColumns time.`
`23`		`- */`
`24`	`19`	`class InsertValues extends AbstractPart`
`25`	`20`	`{`
`26`	`21`	`private string $keyword = 'INSERT INTO';`
`27`	`22`	`private From $table;`
`28`	`23`
`29`		`- /** @var InsertColumnValue[] Normalized column-value pairs */`
	`24`	`+ /** @var InsertColumnValue[] */`
`30`	`25`	`private array $columnValues = [];`
`31`	`26`
`32`	`27`	`private bool $hasSelect = false;`
`@@ -87,11 +82,7 @@ public function getKeyword(): string`
`87`	`82`	`return $this->keyword;`
`88`	`83`	`}`
`89`	`84`
`90`		`- /**`
`91`		`- * Set columns with values, normalizing to InsertColumnValue[].`
`92`		`- *`
`93`		`- * @param array<string, mixed> $columns Column-to-value mapping`
`94`		`- */`
	`85`	`+ /** @param array<string, mixed> $columns */`
`95`	`86`	`public function setColumns(array $columns): void`
`96`	`87`	`{`
`97`	`88`	`$this->columnValues = [];`
`@@ -100,9 +91,6 @@ public function setColumns(array $columns): void`
`100`	`91`	`}`
`101`	`92`	`}`
`102`	`93`
`103`		`- /**`
`104`		`- * Reconstruct the raw column-to-value mapping for compatibility.`
`105`		`- */`
`106`	`94`	`public function getColumns(): array`
`107`	`95`	`{`
`108`	`96`	`$result = [];`
`@@ -117,9 +105,6 @@ public function setHasSelect(bool $hasSelect): void`
`117`	`105`	`$this->hasSelect = $hasSelect;`
`118`	`106`	`}`
`119`	`107`
`120`		`- /**`
`121`		`- * Normalize a raw value to an ArgumentInterface.`
`122`		`- */`
`123`	`108`	`private function normalizeValue(string $column, mixed $value): ArgumentInterface`
`124`	`109`	`{`
`125`	`110`	`if ($value instanceof ArgumentInterface) {`
`@@ -138,7 +123,6 @@ private function normalizeValue(string $column, mixed $value): ArgumentInterface`
`138`	`123`	`return new Literal('NULL');`
`139`	`124`	`}`
`140`	`125`
`141`		`- // Scalar — bind as parameter`
`142`	`126`	`return new Parameter($value, preferredName: $column);`
`143`	`127`	`}`
`144`	`128`	`}`