Feature/storm 82 2 (#89)

Add documentation. (#82)

Author: zantvoort

docs/comparison.md

@@ -233,6 +233,26 @@ Exposed is JetBrains' official Kotlin database framework. It offers two APIs: a
 | **Type Safety** | Column references | Metamodel DSL                        |
 | **Transactions** | Required `transaction {}` block | Optional, programmatic + declarative |
 
+#### Transaction Propagation
+
+Both Storm and Exposed use a `transaction { }` block for programmatic transaction management, but they differ significantly in propagation support.
+
+Exposed's native API supports two modes: shared nesting (the default, where inner blocks join the outer transaction) and savepoint-based nesting (via `useNestedTransactions = true`). For other propagation behaviors, Exposed relies on Spring's `@Transactional` through its `SpringTransactionManager` integration module.
+
+Storm supports all seven standard propagation modes natively in its `transaction { }` block, without requiring Spring:
+
+| Propagation | Storm | Exposed |
+|-------------|-------|---------|
+| `REQUIRED` | Yes | Yes (default behavior) |
+| `REQUIRES_NEW` | Yes | No (Spring only) |
+| `NESTED` | Yes | Yes (`useNestedTransactions`) |
+| `MANDATORY` | Yes | No |
+| `SUPPORTS` | Yes | No |
+| `NOT_SUPPORTED` | Yes | No |
+| `NEVER` | Yes | No |
+
+This means Storm's programmatic API can express patterns like audit logging (`REQUIRES_NEW`), defensive boundary enforcement (`MANDATORY`, `NEVER`), and non-transactional operations (`NOT_SUPPORTED`) directly in code, while Exposed requires Spring integration for these use cases. See [Transactions](transactions.md) for details and examples of each propagation mode.
+
 ### When to Choose Storm
 
 - You need Kotlin and Java support

docs/sql-templates.md

@@ -341,40 +341,36 @@ When working with subqueries or nested template expressions, you may need to con
 | `INNER` | Resolve only within the current (innermost) scope. Fails if the alias is not defined locally. |
 | `OUTER` | Resolve only from outer scope(s), ignoring locally defined aliases. |
 
-The `alias()` and `column()` template functions accept an optional `ResolveScope` parameter:
+The `alias()` and `column()` template functions accept an optional `ResolveScope` parameter. This is most useful in correlated subqueries where the same entity appears in both the outer and inner query. For example, selecting all pets that have at least one visit:
 
 <Tabs groupId="language">
 <TabItem value="kotlin" label="Kotlin" default>
 
 ```kotlin
-orm.query { """
-    SELECT ${User::class}
-    FROM ${User::class}
-    WHERE ${User_.id} IN (
-        SELECT ${column(Order_.userId, ResolveScope.INNER)}
-        FROM ${table(Order::class)}
-        WHERE ${column(Order_.total, ResolveScope.INNER)} > ${1000}
-    )
-""" }
+val pets = orm.entity(Pet::class)
+    .select()
+    .whereExists { subquery(Visit::class)
+        .where { "${column(Visit_.pet, INNER)} = ${column(Pet_.id, OUTER)}" }
+    }
+    .resultList
 ```
 
 </TabItem>
 <TabItem value="java" label="Java">
 
 ```java
-orm.query(RAW."""
-    SELECT \{User.class}
-    FROM \{User.class}
-    WHERE \{User_.id} IN (
-        SELECT \{column(Order_.userId, ResolveScope.INNER)}
-        FROM \{table(Order.class)}
-        WHERE \{column(Order_.total, ResolveScope.INNER)} > \{1000}
-    )""")
+var pets = orm.entity(Pet.class).select()
+        .where(wb -> wb.exists(
+                wb.subquery(Visit.class)
+                        .where(RAW."\{column(Visit_.pet, INNER)} = \{column(Pet_.id, OUTER)}")))
+        .getResultList();
 ```
 
 </TabItem>
 </Tabs>
 
+The `column()` function with a metamodel reference resolves to the fully qualified column name (e.g., `v.pet_id` and `p.id`). `INNER` tells Storm to resolve `Visit_.pet` from the subquery, while `OUTER` resolves `Pet_.id` from the main query.
+
 In most cases the default `CASCADE` scope is correct, because it ensures that each alias resolves to exactly one table. Use `INNER` or `OUTER` when writing correlated subqueries where you need to control whether a reference resolves to the inner query's tables or the outer query's tables.
 
 ---

docs/transactions.md

@@ -14,6 +14,8 @@ Storm works directly with JDBC transactions and supports both programmatic and d
 
 Storm for Kotlin provides a fully programmatic transaction solution (following the style popularized by [Exposed](https://github.com/JetBrains/Exposed)) that is **completely coroutine-friendly**. It supports **all isolation levels and propagation modes** found in traditional transaction management systems. You can freely switch coroutine dispatchers within a transaction (offload CPU-bound work to `Dispatchers.Default` or IO work to `Dispatchers.IO`) and still remain in the **same active transaction**.
 
+While Storm's `transaction { }` blocks look similar to Exposed's, Storm goes further by supporting all seven standard propagation modes (`REQUIRED`, `REQUIRES_NEW`, `NESTED`, `MANDATORY`, `SUPPORTS`, `NOT_SUPPORTED`, `NEVER`). Exposed's native transaction API only supports basic nesting (shared transaction) and savepoint-based nesting (`useNestedTransactions = true`), without the ability to suspend an outer transaction, enforce transactional context, or run non-transactionally. See [Storm vs Exposed](comparison.md#storm-vs-exposed) for a detailed comparison.
+
 The API is designed around Kotlin's type system and coroutine model. Import the transaction functions and enums from `st.orm.template`:
 
 ```kotlin

website/sidebars.ts

@@ -29,12 +29,12 @@ const sidebars: SidebarsConfig = {
           type: 'category',
           label: 'Entity Modeling',
           items: [
-            'polymorphism',
             'converters',
-            'entity-lifecycle',
-            'validation',
             'json',
+            'polymorphism',
+            'entity-lifecycle',
             'serialization',
+            'validation',
           ],
         },
         {