docs: cover SubQuery with comments

Author: constpb2394

src/Injection/SubQuery.php

@@ -16,6 +16,26 @@
 use Cycle\Database\Query\QueryParameters;
 use Cycle\Database\Query\SelectQuery;
 
+/**
+ * This fragment is used to inject a whole select statement into
+ * FROM and SELECT parts of the query.
+ *
+ * Examples:
+ *
+ * ```
+ *  $subQuery = new SubQuery($queryBuilder->select()->from(['users']),'u');
+ *  $query = $queryBuilder->select()->from($subQuery);
+ * ```
+ *
+ * Will provide SQL like this: SELECT * FROM (SELECT * FROM users) AS u
+ *
+ * ```
+ *  $subQuery = new SubQuery($queryBuilder->select()->from(['users']),'u');
+ *  $query = $queryBuilder->select($subQuery)->from(['employee']);
+ * ```
+ *
+ * Will provide SQL like this: SELECT *, (SELECT * FROM users) AS u FROM employee
+ */
 class SubQuery implements FragmentInterface
 {
     private SelectQuery $query;

src/Query/SelectQuery.php

@@ -13,6 +13,7 @@
 
 use Cycle\Database\Injection\Expression;
 use Cycle\Database\Injection\Fragment;
+use Cycle\Database\Injection\SubQuery;
 use Cycle\Database\Query\Traits\WhereJsonTrait;
 use Cycle\Database\Driver\CompilerInterface;
 use Cycle\Database\Injection\FragmentInterface;
@@ -84,6 +85,16 @@ public function distinct(bool|string|FragmentInterface $distinct = true): self
     /**
      * Set table names SELECT query should be performed for. Table names can be provided with
      * specified alias (AS construction).
+     * Also, it is possible to use SubQuery.
+     *
+     * Following example will provide SQL like this: SELECT * FROM (SELECT * FROM users) AS u
+     *
+     * ```
+     *  $subQuery = new SubQuery($queryBuilder->select()->from(['users']),'u');
+     *  $query = $queryBuilder->select()->from($subQuery);
+     * ```
+     *
+     * @see SubQuery
      */
     public function from(mixed $tables): self
     {