Improve documentation. (#90) (#92)

Author: zantvoort

docs/comparison.md

@@ -44,18 +44,20 @@ The following tables provide a side-by-side comparison of concrete features acro
 
 | Feature | Storm | JPA | Spring Data | MyBatis | jOOQ | JDBI | Exposed | Ktorm |
 |---------|-------|-----|-------------|---------|------|------|---------|-------|
-| Transactions | Both | Both | Declarative | Both | Programmatic | Both | Required | Required |
+| Transactions | Both | Both | Declarative | Both | Programmatic | Both | Both<sup>6</sup> | Required |
 | Schema validation | Yes | Yes | Via JPA | No | N/A<sup>5</sup> | No | Yes | No |
 | Java support | Yes | Yes | Yes | Yes | Yes | Yes | No | No |
 | Kotlin support | First-class | Good | Good | Good | Good | Good | Native | Native |
 | Coroutines | Yes | No | No | No | No | No | Yes | Limited |
 | Spring integration | Yes | Yes | Native | Yes | Yes | Yes | Yes | Yes |
-| Runtime mechanism | Codegen<sup>6</sup> | Bytecode | Bytecode | Reflection | Codegen | Reflection | Reflection | Reflection |
+| Runtime mechanism | Codegen<sup>7</sup> | Bytecode | Bytecode | Reflection | Codegen | Reflection | Reflection | Reflection |
 | Community | New | Huge | Huge | Large | Medium | Medium | Medium | Small |
 
 <sup>5</sup> jOOQ generates code from the database schema, so schema validation is inherent in its code generation step.
 
-<sup>6</sup> Storm uses codegen with reflection fallback.
+<sup>6</sup> Exposed requires `transaction {}` blocks natively, but supports declarative `@Transactional` via its Spring integration module.
+
+<sup>7</sup> Storm uses codegen with reflection fallback.
 
 ---
 
@@ -85,6 +87,7 @@ JPA (typically implemented by Hibernate) is the most widely used persistence fra
 - N+1 queries have been a recurring problem
 - You prefer immutable data structures
 - You value simplicity over complexity
+- You want a lightweight, minimal dependency footprint
 - You're using Kotlin and want idiomatic APIs
 
 ### When to Choose JPA/Hibernate
@@ -114,6 +117,7 @@ Spring Data JPA wraps JPA with a repository abstraction that derives query imple
 - You want stateless, immutable entities
 - You prefer explicit query logic over naming conventions
 - You want to avoid JPA's complexity
+- You want a lightweight, minimal dependency footprint
 
 ### When to Choose Spring Data JPA
 
@@ -231,7 +235,7 @@ Exposed is JetBrains' official Kotlin database framework. It offers two APIs: a
 | **N+1 Problem** | Possible with DAO | Prevented by design; requires explicit opt-in                 |
 | **Coroutines** | Supported (added later) | First-class from the start           |
 | **Type Safety** | Column references | Metamodel DSL                        |
-| **Transactions** | Required `transaction {}` block | Optional, programmatic + declarative |
+| **Transactions** | `transaction {}` block, declarative via Spring module | Optional, programmatic + declarative |
 
 #### Transaction Propagation
 
@@ -304,7 +308,6 @@ Ktorm is a lightweight Kotlin ORM that uses entity interfaces and DSL-based tabl
 - You're building a Kotlin-only project
 - You prefer no code generation
 - You like the Sequence API style
-- You want a lightweight, minimal dependency footprint
 - You prefer DSL-based table definitions
 
 ## Summary

docs/first-entity.md

@@ -33,11 +33,13 @@ Non-nullable fields (like `city: City`) produce `INNER JOIN` queries. Nullable f
 <TabItem value="java" label="Java">
 
 ```java
+@Builder(toBuilder = true)
 record City(@PK Integer id,
             String name,
             long population
 ) implements Entity<Integer> {}
 
+@Builder(toBuilder = true)
 record User(@PK Integer id,
             String email,
             String name,
@@ -47,6 +49,8 @@ record User(@PK Integer id,
 
 In Java, record components are nullable by default. Use `@Nonnull` on fields that must always have a value. Primitive types (`int`, `long`, etc.) are inherently non-nullable.
 
+The `@Builder` annotation is from [Lombok](https://projectlombok.org/) and is optional. It generates a builder that lets you construct entities without specifying the primary key, and creates modified copies via `toBuilder()`. Without Lombok, you can pass `null` as the primary key (e.g., `new City(null, "Sunnyvale", 155_000)`) or define a convenience constructor that omits it. See [Modifying Entities](entities.md#modifying-entities) for details.
+
 </TabItem>
 </Tabs>
 
@@ -129,10 +133,17 @@ var cities = orm.entity(City.class);
 var users = orm.entity(User.class);
 
 // Insert a city -- the returned object has the database-generated ID
-City city = cities.insertAndFetch(new City(null, "Sunnyvale", 155_000));
+City city = cities.insertAndFetch(City.builder()
+        .name("Sunnyvale")
+        .population(155_000)
+        .build());
 
 // Insert a user that references the city
-User user = users.insertAndFetch(new User(null, "alice@example.com", "Alice", city));
+User user = users.insertAndFetch(User.builder()
+        .email("alice@example.com")
+        .name("Alice")
+        .city(city)
+        .build());
 ```
 
 The `insertAndFetch` method sends an INSERT statement, retrieves the auto-generated primary key, and returns a new record with the key populated.
@@ -237,7 +248,11 @@ With Spring's `@Transactional`:
 @Transactional
 public User createUser(String email, String name, City city) {
     return orm.entity(User.class)
-        .insertAndFetch(new User(null, email, name, city));
+        .insertAndFetch(User.builder()
+                .email(email)
+                .name(name)
+                .city(city)
+                .build());
 }
 ```
 

docs/index.md

@@ -23,7 +23,7 @@ import TabItem from '@theme/TabItem';
 
 ## Why Storm?
 
-Storm draws inspiration from established ORMs such as Hibernate, but is built from scratch around a clear design philosophy: capturing exactly what you want to do using the minimum amount of code, optimized for Kotlin and modern Java
+Storm draws inspiration from established ORMs such as Hibernate, but is built from scratch around a clear design philosophy: capture intent using the minimum amount of code, optimized for Kotlin and modern Java.
 
 **Storm's mission:** Make database development productive and enjoyable, with full developer control and high performance.
 

website/versioned_docs/version-1.10.0/comparison.md

@@ -44,18 +44,20 @@ The following tables provide a side-by-side comparison of concrete features acro
 
 | Feature | Storm | JPA | Spring Data | MyBatis | jOOQ | JDBI | Exposed | Ktorm |
 |---------|-------|-----|-------------|---------|------|------|---------|-------|
-| Transactions | Both | Both | Declarative | Both | Programmatic | Both | Required | Required |
+| Transactions | Both | Both | Declarative | Both | Programmatic | Both | Both<sup>6</sup> | Required |
 | Schema validation | Yes | Yes | Via JPA | No | N/A<sup>5</sup> | No | Yes | No |
 | Java support | Yes | Yes | Yes | Yes | Yes | Yes | No | No |
 | Kotlin support | First-class | Good | Good | Good | Good | Good | Native | Native |
 | Coroutines | Yes | No | No | No | No | No | Yes | Limited |
 | Spring integration | Yes | Yes | Native | Yes | Yes | Yes | Yes | Yes |
-| Runtime mechanism | Codegen<sup>6</sup> | Bytecode | Bytecode | Reflection | Codegen | Reflection | Reflection | Reflection |
+| Runtime mechanism | Codegen<sup>7</sup> | Bytecode | Bytecode | Reflection | Codegen | Reflection | Reflection | Reflection |
 | Community | New | Huge | Huge | Large | Medium | Medium | Medium | Small |
 
 <sup>5</sup> jOOQ generates code from the database schema, so schema validation is inherent in its code generation step.
 
-<sup>6</sup> Storm uses codegen with reflection fallback.
+<sup>6</sup> Exposed requires `transaction {}` blocks natively, but supports declarative `@Transactional` via its Spring integration module.
+
+<sup>7</sup> Storm uses codegen with reflection fallback.
 
 ---
 
@@ -85,6 +87,7 @@ JPA (typically implemented by Hibernate) is the most widely used persistence fra
 - N+1 queries have been a recurring problem
 - You prefer immutable data structures
 - You value simplicity over complexity
+- You want a lightweight, minimal dependency footprint
 - You're using Kotlin and want idiomatic APIs
 
 ### When to Choose JPA/Hibernate
@@ -114,6 +117,7 @@ Spring Data JPA wraps JPA with a repository abstraction that derives query imple
 - You want stateless, immutable entities
 - You prefer explicit query logic over naming conventions
 - You want to avoid JPA's complexity
+- You want a lightweight, minimal dependency footprint
 
 ### When to Choose Spring Data JPA
 
@@ -231,7 +235,7 @@ Exposed is JetBrains' official Kotlin database framework. It offers two APIs: a
 | **N+1 Problem** | Possible with DAO | Prevented by design; requires explicit opt-in                 |
 | **Coroutines** | Supported (added later) | First-class from the start           |
 | **Type Safety** | Column references | Metamodel DSL                        |
-| **Transactions** | Required `transaction {}` block | Optional, programmatic + declarative |
+| **Transactions** | `transaction {}` block, declarative via Spring module | Optional, programmatic + declarative |
 
 #### Transaction Propagation
 
@@ -304,7 +308,6 @@ Ktorm is a lightweight Kotlin ORM that uses entity interfaces and DSL-based tabl
 - You're building a Kotlin-only project
 - You prefer no code generation
 - You like the Sequence API style
-- You want a lightweight, minimal dependency footprint
 - You prefer DSL-based table definitions
 
 ## Summary

website/versioned_docs/version-1.10.0/first-entity.md

@@ -33,11 +33,13 @@ Non-nullable fields (like `city: City`) produce `INNER JOIN` queries. Nullable f
 <TabItem value="java" label="Java">
 
 ```java
+@Builder(toBuilder = true)
 record City(@PK Integer id,
             String name,
             long population
 ) implements Entity<Integer> {}
 
+@Builder(toBuilder = true)
 record User(@PK Integer id,
             String email,
             String name,
@@ -47,6 +49,8 @@ record User(@PK Integer id,
 
 In Java, record components are nullable by default. Use `@Nonnull` on fields that must always have a value. Primitive types (`int`, `long`, etc.) are inherently non-nullable.
 
+The `@Builder` annotation is from [Lombok](https://projectlombok.org/) and is optional. It generates a builder that lets you construct entities without specifying the primary key, and creates modified copies via `toBuilder()`. Without Lombok, you can pass `null` as the primary key (e.g., `new City(null, "Sunnyvale", 155_000)`) or define a convenience constructor that omits it. See [Modifying Entities](entities.md#modifying-entities) for details.
+
 </TabItem>
 </Tabs>
 
@@ -129,10 +133,17 @@ var cities = orm.entity(City.class);
 var users = orm.entity(User.class);
 
 // Insert a city -- the returned object has the database-generated ID
-City city = cities.insertAndFetch(new City(null, "Sunnyvale", 155_000));
+City city = cities.insertAndFetch(City.builder()
+        .name("Sunnyvale")
+        .population(155_000)
+        .build());
 
 // Insert a user that references the city
-User user = users.insertAndFetch(new User(null, "alice@example.com", "Alice", city));
+User user = users.insertAndFetch(User.builder()
+        .email("alice@example.com")
+        .name("Alice")
+        .city(city)
+        .build());
 ```
 
 The `insertAndFetch` method sends an INSERT statement, retrieves the auto-generated primary key, and returns a new record with the key populated.
@@ -237,7 +248,11 @@ With Spring's `@Transactional`:
 @Transactional
 public User createUser(String email, String name, City city) {
     return orm.entity(User.class)
-        .insertAndFetch(new User(null, email, name, city));
+        .insertAndFetch(User.builder()
+                .email(email)
+                .name(name)
+                .city(city)
+                .build());
 }
 ```
 

website/versioned_docs/version-1.10.0/index.md

@@ -23,7 +23,7 @@ import TabItem from '@theme/TabItem';
 
 ## Why Storm?
 
-Storm draws inspiration from established ORMs such as Hibernate, but is built from scratch around a clear design philosophy: capturing exactly what you want to do using the minimum amount of code, optimized for Kotlin and modern Java
+Storm draws inspiration from established ORMs such as Hibernate, but is built from scratch around a clear design philosophy: capture intent using the minimum amount of code, optimized for Kotlin and modern Java.
 
 **Storm's mission:** Make database development productive and enjoyable, with full developer control and high performance.