docs: enhance PHPDoc with examples, warnings, and documentation links

Add comprehensive @example tags with usage examples for:
- DmlQueryBuilder::insertFrom() - INSERT ... SELECT operations
- SelectQueryBuilder::getColumn() - column extraction with index()
- DmlQueryBuilder::merge() - MERGE/UPSERT operations
- SelectQueryBuilder::paginate() - pagination with metadata
- QueryBuilder::withRecursive() - recursive CTEs for hierarchies
- ColumnSchema::defaultValue() - default value handling
- SelectQueryBuilder::groupBy() - GROUP BY with JOINs
- DdlBuilderTrait::createIndex() - advanced index creation
- Model::relations() - ActiveRecord relationships
- ConditionalHelpersTrait::case() - CASE statements

Add @warning tags for:
- MSSQL IDENTITY column handling in insertFrom()
- Dialect-specific differences in merge() and createIndex()
- Performance considerations in paginate()
- MSSQL reserved words in case() and groupBy()

Add @see tags linking to relevant documentation files.

Improve developer experience with inline examples and clear warnings.

Author: tommyknocker

src/helpers/traits/ConditionalHelpersTrait.php

@@ -14,10 +14,51 @@ trait ConditionalHelpersTrait
     /**
      * Returns a RawValue instance representing a CASE statement.
      *
+     * Generates a SQL CASE expression with automatic identifier quoting for MSSQL reserved words.
+     *
      * @param array<string, string> $cases An associative array where keys are WHEN conditions and values are THEN results.
      * @param string|null $else An optional ELSE result.
      *
      * @return RawValue The RawValue instance for the CASE statement.
+     *
+     * @example
+     * // Simple CASE statement
+     * $db->find()
+     *     ->from('users')
+     *     ->select([
+     *         'status_label' => Db::case([
+     *             "status = 'active'" => "'Active'",
+     *             "status = 'inactive'" => "'Inactive'",
+     *         ], "'Unknown'")
+     *     ])
+     *     ->get();
+     * @example
+     * // CASE with MSSQL reserved words (automatically quoted)
+     * $db->find()
+     *     ->from('plans')
+     *     ->select([
+     *         'plan_type' => Db::case([
+     *             "plan = 'basic'" => "'Basic Plan'",
+     *             "plan = 'premium'" => "'Premium Plan'",
+     *         ])
+     *     ])
+     *     ->get();
+     * @example
+     * // CASE in WHERE clause
+     * $db->find()
+     *     ->from('orders')
+     *     ->where(Db::case([
+     *         "status = 'pending'" => '1',
+     *         "status = 'processing'" => '1',
+     *     ], '0'), '1')
+     *     ->get();
+     *
+     * @note For MSSQL: Identifiers in WHEN conditions are automatically quoted if they are
+     *       reserved words (e.g., 'plan', 'order', 'group'). This prevents syntax errors.
+     *
+     * @warning WHEN conditions should be valid SQL expressions. Use Db::raw() for complex expressions.
+     *
+     * @see documentation/07-helper-functions/06-comparison-helpers.md
      */
     public static function case(array $cases, string|null $else = null): RawValue
     {

src/orm/Model.php

@@ -96,15 +96,81 @@ public static function rules(): array
     /**
      * Get relationship definitions.
      *
+     * Defines ActiveRecord relationships for lazy and eager loading.
+     * Supports hasOne, hasMany, belongsTo, and hasManyThrough relationships.
+     *
      * Format: [
      *   'relationName' => ['hasOne', 'modelClass' => RelatedModel::class, 'foreignKey' => '...', 'localKey' => '...'],
      *   'relationName' => ['hasMany', 'modelClass' => RelatedModel::class, 'foreignKey' => '...', 'localKey' => '...'],
      *   'relationName' => ['belongsTo', 'modelClass' => RelatedModel::class, 'foreignKey' => '...', 'ownerKey' => '...'],
+     *   'relationName' => ['hasManyThrough', 'modelClass' => RelatedModel::class, 'viaTable' => '...', 'link' => [...], 'viaLink' => [...]],
      * ]
      *
      * Override this method to define relationships for the model.
      *
      * @return array<string, array<int|string, mixed>> Relationship definitions
+     *
+     * @example
+     * // User has one Profile
+     * public static function relations(): array
+     * {
+     *     return [
+     *         'profile' => [
+     *             'hasOne',
+     *             'modelClass' => Profile::class,
+     *             'foreignKey' => 'user_id',
+     *             'localKey' => 'id'
+     *         ]
+     *     ];
+     * }
+     * @example
+     * // User has many Posts
+     * public static function relations(): array
+     * {
+     *     return [
+     *         'posts' => [
+     *             'hasMany',
+     *             'modelClass' => Post::class,
+     *             'foreignKey' => 'user_id',
+     *             'localKey' => 'id'
+     *         ]
+     *     ];
+     * }
+     * @example
+     * // Post belongs to User
+     * public static function relations(): array
+     * {
+     *     return [
+     *         'user' => [
+     *             'belongsTo',
+     *             'modelClass' => User::class,
+     *             'foreignKey' => 'user_id',
+     *             'ownerKey' => 'id'
+     *         ]
+     *     ];
+     * }
+     * @example
+     * // Many-to-many via junction table
+     * public static function relations(): array
+     * {
+     *     return [
+     *         'projects' => [
+     *             'hasManyThrough',
+     *             'modelClass' => Project::class,
+     *             'viaTable' => 'user_project',
+     *             'link' => ['id' => 'user_id'],
+     *             'viaLink' => ['project_id' => 'id']
+     *         ]
+     *     ];
+     * }
+     *
+     * @note Relationships can be accessed as properties (lazy loading) or via with() (eager loading).
+     *       Use eager loading to prevent N+1 query problems.
+     *
+     * @warning Foreign key and local key parameters are required for all relationship types.
+     *
+     * @see Model::with() For eager loading relationships
+     * @see documentation/05-advanced-features/17-active-record-relationships.md
      */
     public static function relations(): array
     {

src/query/DmlQueryBuilder.php

@@ -197,11 +197,42 @@ public function insert(array $data, array $onDuplicate = []): int
     /**
      * Insert data from a SELECT query or subquery.
      *
+     * Supports INSERT ... SELECT with ON DUPLICATE KEY UPDATE (MySQL/MariaDB),
+     * ON CONFLICT (PostgreSQL), and MERGE (MSSQL).
+     *
      * @param string|\Closure(QueryBuilder): void|SelectQueryBuilderInterface|QueryBuilder $source Source query (table name, QueryBuilder, SelectQueryBuilderInterface, or Closure)
      * @param array<string>|null $columns Column names to insert into (null = use SELECT columns)
      * @param array<string, string|int|float|bool|null|RawValue> $onDuplicate The columns to update on duplicate.
      *
      * @return int The result of the insert operation.
+     *
+     * @example
+     * // Basic INSERT ... SELECT
+     * $db->find()
+     *     ->table('target_table')
+     *     ->insertFrom('source_table');
+     * @example
+     * // INSERT ... SELECT with specific columns
+     * $db->find()
+     *     ->table('target_table')
+     *     ->insertFrom('source_table', ['id', 'name', 'email']);
+     * @example
+     * // INSERT ... SELECT with ON DUPLICATE KEY UPDATE (MySQL)
+     * $db->find()
+     *     ->table('target_table')
+     *     ->insertFrom('source_table', null, ['name' => Db::raw('VALUES(name)'), 'updated_at' => Db::now()]);
+     * @example
+     * // INSERT ... SELECT from QueryBuilder
+     * $db->find()
+     *     ->table('target_table')
+     *     ->insertFrom(function($query) {
+     *         $query->from('source_table')->where('status', 'active');
+     *     });
+     *
+     * @warning For MSSQL: IDENTITY columns are automatically excluded from INSERT column list
+     *          when columns are not explicitly provided. This prevents "IDENTITY_INSERT" errors.
+     *
+     * @see documentation/03-query-builder/02-data-manipulation.md#insert--select-copy-data-between-tables
      */
     public function insertFrom(
         string|\Closure|SelectQueryBuilderInterface|QueryBuilder $source,
@@ -869,14 +900,49 @@ protected function processValueForSql(mixed $value, string $columnName, string $
     /**
      * Execute MERGE statement (INSERT/UPDATE/DELETE based on match conditions).
      *
+     * Performs INSERT ... ON CONFLICT UPDATE (PostgreSQL), INSERT ... ON DUPLICATE KEY UPDATE (MySQL),
+     * or MERGE (MSSQL) operations. This is a powerful way to synchronize data between tables.
+     *
      * @param string|\Closure(QueryBuilder): void|SelectQueryBuilderInterface $source Source table/subquery for MERGE
-     * @param string|array<string> $onConditions ON clause conditions
+     * @param string|array<string> $onConditions ON clause conditions (e.g., ['target.id = source.id'])
      * @param array<string, string|int|float|bool|null|RawValue> $whenMatched Update columns when matched
      * @param array<string, string|int|float|bool|null|RawValue> $whenNotMatched Insert columns when not matched
      * @param bool $whenNotMatchedBySourceDelete Delete when not matched by source
      *
      * @return int Number of affected rows
      * @throws RuntimeException If MERGE is not supported by dialect
+     *
+     * @example
+     * // MERGE/UPSERT from table
+     * $db->find()
+     *     ->table('target_users')
+     *     ->merge('source_users', ['target_users.id = source_users.id'], [
+     *         'name' => Db::raw('source_users.name'),
+     *         'updated_at' => Db::now()
+     *     ], [
+     *         'id' => Db::raw('source_users.id'),
+     *         'name' => Db::raw('source_users.name')
+     *     ]);
+     * @example
+     * // MERGE/UPSERT from QueryBuilder
+     * $db->find()
+     *     ->table('target_users')
+     *     ->merge(function($query) {
+     *         $query->from('source_users')->where('status', 'active');
+     *     }, ['target_users.id = source_users.id'], [
+     *         'name' => Db::raw('source_users.name')
+     *     ]);
+     *
+     * @warning MERGE syntax differs between databases:
+     *          - PostgreSQL: Uses INSERT ... ON CONFLICT
+     *          - MySQL/MariaDB: Uses INSERT ... ON DUPLICATE KEY UPDATE
+     *          - MSSQL: Uses MERGE statement
+     *          - SQLite: Not supported, throws exception
+     *
+     * @note For MSSQL, use table aliases in ON conditions (e.g., 'target.id = source.id').
+     *       For PostgreSQL/MySQL, the conflict target is automatically detected from ON conditions.
+     *
+     * @see documentation/05-advanced-features/05-upsert-operations.md
      */
     public function merge(
         string|\Closure|SelectQueryBuilderInterface $source,

src/query/QueryBuilder.php

@@ -455,11 +455,53 @@ public function with(
     /**
      * Add a recursive Common Table Expression (CTE) to the query.
      *
+     * Creates a recursive Common Table Expression (WITH RECURSIVE) for hierarchical queries,
+     * tree traversal, and other recursive data structures.
+     *
      * @param string $name CTE name
      * @param QueryBuilder|Closure(QueryBuilder): void|string|RawValue $query Query with UNION ALL structure
      * @param array<string> $columns Explicit column list (recommended for recursive CTEs)
      *
      * @return static The current instance.
+     *
+     * @example
+     * // Hierarchical category tree
+     * $categories = $db->find()
+     *     ->withRecursive('category_tree', function($q) {
+     *         $q->from('categories')
+     *           ->select(['id', 'name', 'parent_id', Db::raw('0 as level')])
+     *           ->where('parent_id', null, 'IS');
+     *     }, function($r) {
+     *         $r->from('categories c')
+     *           ->select(['c.id', 'c.name', 'c.parent_id', Db::raw('ct.level + 1 as level')])
+     *           ->join('category_tree ct', 'c.parent_id = ct.id');
+     *     })
+     *     ->from('category_tree')
+     *     ->orderBy('level')
+     *     ->orderBy('name')
+     *     ->get();
+     * @example
+     * // Employee hierarchy
+     * $employees = $db->find()
+     *     ->withRecursive('employee_tree', function($q) {
+     *         $q->from('employees')
+     *           ->select(['id', 'name', 'manager_id', Db::raw('1 as depth')])
+     *           ->where('manager_id', null, 'IS');
+     *     }, function($r) {
+     *         $r->from('employees e')
+     *           ->select(['e.id', 'e.name', 'e.manager_id', Db::raw('et.depth + 1')])
+     *           ->join('employee_tree et', 'e.manager_id = et.id');
+     *     })
+     *     ->from('employee_tree')
+     *     ->get();
+     *
+     * @warning Recursive CTEs require careful design to avoid infinite loops.
+     *          Always ensure the recursive part eventually terminates.
+     *
+     * @note Column names are auto-detected from SELECT clauses if not provided.
+     *       Explicit column names improve performance and prevent errors.
+     *
+     * @see documentation/03-query-builder/08-cte.md#recursive-ctes
      */
     public function withRecursive(
         string $name,