Enhance Documentation

groue · groue · commit 71880a9b8e56 · 2022-11-09T13:20:08.000+01:00
diff --git a/GRDB/Core/Configuration.swift b/GRDB/Core/Configuration.swift
@@ -1,21 +1,24 @@
 import Dispatch
 import Foundation
 
-/// The configuration of a ``Database``, ``DatabaseQueue``, or ``DatabasePool``.
+/// The configuration of a database connection.
 ///
-/// Usage:
+/// You create a `Configuration` before opening a database connection:
 ///
 /// ```swift
 /// var config = Configuration()
 /// config.readonly = true
-/// config.foreignKeysEnabled = true // Default is already true
-/// config.label = "MyDatabase"      // Useful when your app opens multiple databases
-/// config.maximumReaderCount = 10   // (DatabasePool only) The default is 5
+/// config.maximumReaderCount = 2  // (DatabasePool only) The default is 5
+/// config.prepareDatabase { db in // A function to run on connection
+///     db.trace { print("SQL >", $0) }
+/// }
 ///
 /// let dbQueue = try DatabaseQueue( // or DatabasePool
 ///     path: "/path/to/database.sqlite",
 ///     configuration: config)
 /// ```
+///
+/// See <doc:DatabaseConnections>.
 public struct Configuration {
     
     // MARK: - Misc options
diff --git a/GRDB/Core/Database.swift b/GRDB/Core/Database.swift
@@ -10,16 +10,14 @@ let SQLITE_TRANSIENT = unsafeBitCast(OpaquePointer(bitPattern: -1), to: sqlite3_
 
 /// An SQLite connection.
 ///
-/// You don't create `Database` instances directly. Instead, you use a database
-/// access method from ``DatabaseQueue``, ``DatabasePool``.
-/// ``DatabaseSnapshot``, ``DatabaseMigrator`` or ``ValueObservation``.
-/// For example:
+/// You don't create `Database` instances directly. Instead, you connect to a
+/// database with one of the <doc:DatabaseConnections>, and you use a database
+/// access method. For example:
 ///
 /// ```swift
 /// let dbQueue = try DatabaseQueue()
 ///
-/// // The Database is the `db` in the closure:
-/// try dbQueue.write { db in
+/// try dbQueue.write { (db: Database) in
 ///     try Player(name: "Arthur").insert(db)
 /// }
 /// ```
@@ -71,7 +69,6 @@ let SQLITE_TRANSIENT = unsafeBitCast(OpaquePointer(bitPattern: -1), to: sqlite3_
 /// - ``add(transactionObserver:extent:)``
 /// - ``afterNextTransaction(onCommit:onRollback:)``
 /// - ``remove(transactionObserver:)``
-/// - ``TransactionObserver``
 /// - ``TransactionObservationExtent``
 ///
 /// ### Collations
diff --git a/GRDB/Core/DatabasePool.swift b/GRDB/Core/DatabasePool.swift
@@ -31,6 +31,9 @@ import UIKit
 ///
 /// ### Accessing the Database
 ///
+/// See ``DatabaseReader`` and ``DatabaseWriter`` for more database
+/// access methods.
+///
 /// - ``asyncConcurrentRead(_:)``
 /// - ``writeInTransaction(_:_:)``
 ///
diff --git a/GRDB/Core/DatabaseQueue.swift b/GRDB/Core/DatabaseQueue.swift
@@ -22,6 +22,9 @@ import UIKit
 ///
 /// ### Accessing the Database
 ///
+/// See ``DatabaseReader`` and ``DatabaseWriter`` for more database
+/// access methods.
+///
 /// - ``inDatabase(_:)``
 /// - ``inTransaction(_:_:)``
 ///
diff --git a/GRDB/Core/DatabaseReader.swift b/GRDB/Core/DatabaseReader.swift
@@ -3,7 +3,7 @@ import Combine
 #endif
 import Dispatch
 
-/// The protocol for types that read from an SQLite database.
+/// A type that reads from an SQLite database.
 ///
 /// Do not declare new conformances to `DatabaseReader`. Only the
 /// ``DatabaseQueue``, ``DatabasePool``, and ``DatabaseSnapshot`` types are
diff --git a/GRDB/Core/DatabaseWriter.swift b/GRDB/Core/DatabaseWriter.swift
@@ -3,7 +3,7 @@ import Combine
 #endif
 import Dispatch
 
-/// The protocol for types that write into an SQLite database.
+/// A type that write into an SQLite database.
 ///
 /// Do not declare new conformances to `DatabaseWriter`. Only the
 /// ``DatabaseQueue`` and ``DatabasePool`` types are valid conforming types.
diff --git a/GRDB/Core/SQLRequest.swift b/GRDB/Core/SQLRequest.swift
@@ -16,7 +16,7 @@
 ///
 /// try dbQueue.read { db in
 ///     let players = try Player.filter(name: "O'Brien").fetchAll(db) // [Player]
-///     let maxScore = Player.maximumScore().fetchOne(db)             // Int?
+///     let maxScore = try Player.maximumScore().fetchOne(db)         // Int?
 /// }
 /// ```
 ///
diff --git a/GRDB/Core/Statement.swift b/GRDB/Core/Statement.swift
@@ -515,7 +515,7 @@ extension Statement {
 /// try dbQueue.read { db in
 ///     // A cursor of database rows,
 ///     // built from a prepared statement
-///     let statement = db.makeStatement(sql: "SELECT * FROM player")
+///     let statement = try db.makeStatement(sql: "SELECT * FROM player")
 ///     let rows = try Row.fetchCursor(statement)
 ///     while let row = try rows.next() {
 ///         let id: Int64 = row["id"]
@@ -603,15 +603,17 @@ extension DatabaseCursor {
 }
 
 /// A cursor that iterates a database statement without producing any value.
-/// Each call to the next() cursor method calls the sqlite3_step() C function.
+/// Each call to the `next()` method calls the `sqlite3_step()` C function.
 ///
 /// For example:
 ///
-///     try dbQueue.read { db in
-///         let statement = db.makeStatement(sql: "SELECT performSideEffect()")
-///         let cursor = statement.makeCursor()
-///         try cursor.next()
-///     }
+/// ```swift
+/// try dbQueue.read { db in
+///     let statement = try db.makeStatement(sql: "SELECT performSideEffect()")
+///     let cursor = statement.makeCursor()
+///     try cursor.next()
+/// }
+/// ```
 final class StatementCursor: DatabaseCursor {
     typealias Element = Void
     let _statement: Statement
diff --git a/GRDB/Core/TransactionObserver.swift b/GRDB/Core/TransactionObserver.swift
@@ -723,8 +723,8 @@ class DatabaseObservationBroker {
 ///
 /// An observer starts receiving change notifications after it has been added to
 /// a database connection with the
-/// ``DatabaseWriter/add(transactionObserver:extent:)`` or
-/// ``Database/add(transactionObserver:extent:)`` methods.
+/// ``DatabaseWriter/add(transactionObserver:extent:)`` `DatabaseWriter` method,
+/// or the ``Database/add(transactionObserver:extent:)`` `Database` method.
 ///
 /// All observer methods are called in a the writer dispatch queue, serialized
 /// with all database updates (see ``DatabaseWriter``).
diff --git a/GRDB/Documentation.docc/DatabaseConnections.md b/GRDB/Documentation.docc/DatabaseConnections.md
@@ -2,17 +2,41 @@
 
 Open database connections to SQLite databases. 
 
+## Overview
+
+GRDB provides two classes for accessing SQLite databases: ``DatabaseQueue`` and ``DatabasePool``:
+
+```swift
+import GRDB
+
+// Pick one:
+let dbQueue = try DatabaseQueue(path: "/path/to/database.sqlite")
+let dbPool = try DatabasePool(path: "/path/to/database.sqlite")
+```
+
+The differences are:
+
+- `DatabasePool` allows concurrent database accesses (this can improve the performance of multithreaded applications).
+- `DatabasePool` opens your SQLite database in the [WAL mode](https://www.sqlite.org/wal.html) (unless read-only).
+- `DatabaseQueue` supports [in-memory databases](https://www.sqlite.org/inmemorydb.html).
+
+**If you are not sure, choose `DatabaseQueue`.** You will always be able to switch to `DatabasePool` later.
+
 ## Topics
 
-### Opening Database Connections
+### Configuring Database Connections
 
 - ``Configuration``
-- ``DatabasePool``
+
+### Opening Database Connections
+
 - ``DatabaseQueue``
+- ``DatabasePool``
 - ``DatabaseSnapshot``
 - ``DatabaseReader``
 - ``DatabaseWriter``
 
 ### Using Database Connections
 
 - ``Database``
+- ``DatabaseError``
diff --git a/GRDB/Documentation.docc/DatabaseObservation.md b/GRDB/Documentation.docc/DatabaseObservation.md
@@ -6,13 +6,16 @@ Observe database changes and transactions.
 
 ### Observing Database Values
 
-- ``AsyncValueObservation``
-- ``SharedValueObservation``
 - ``ValueObservation``
+- ``SharedValueObservation``
+- ``AsyncValueObservation``
 
 ### Observing Database Transactions
 
-- ``DatabaseRegion``
 - ``DatabaseRegionObservation``
-- ``DatabaseRegionConvertible``
 - ``TransactionObserver``
+
+### Database Regions
+
+- ``DatabaseRegion``
+- ``DatabaseRegionConvertible``
diff --git a/GRDB/Documentation.docc/DatabaseSchema.md b/GRDB/Documentation.docc/DatabaseSchema.md
@@ -27,7 +27,7 @@ But you should prefer wrapping your schema changes in <doc:Migrations> when you
 > - Dropping a table column requires SQLite 3.35+ (iOS 15.0, tvOS 15.0, watchOS 8.0, macOS 12.0).
 > - [Strict tables](https://www.sqlite.org/stricttables.html) require SQLite 3.37+ (iOS 15.4, macOS 12.4, tvOS 15.4, watchOS 8.5).
 >
-> When you need to perform a schema change that is not directly supported, or not available, you will sometimes need to recreate database tables. See <doc:Migrations> for the detailed procedure. 
+> When you need to modify a table in a way that is not directly supported by SQLite, or not available on your target operating system, you will need to recreate the database table. See <doc:Migrations> for the detailed procedure.  
 
 ## Topics
 
diff --git a/GRDB/Documentation.docc/Documentation.md b/GRDB/Documentation.docc/Documentation.md
@@ -13,7 +13,6 @@ GRDB provides raw access to SQL and advanced SQLite features, because one someti
 
 - <doc:DatabaseConnections>
 - <doc:SQLSupport>
-- <doc:Errors>
 
 ### Migrations and The Database Schema
 
diff --git a/GRDB/Documentation.docc/Errors.md b/GRDB/Documentation.docc/Errors.md
diff --git a/GRDB/Documentation.docc/Migrations.md b/GRDB/Documentation.docc/Migrations.md
@@ -85,9 +85,19 @@ try dbQueue.read { db in
 
 ## Defining the Database Schema from a Migration
 
-See <doc:DatabaseSchema> for the methods that define the database schema.
+See <doc:DatabaseSchema> for the methods that define the database schema. For example:
 
-When you need to perform a schema change that is not directly supported by SQLite, or not available on your target operating system, you will need to recreate database tables.
+```swift
+migrator.registerMigration("Create authors") { db in
+    try db.create(table: "author") { t in
+        t.autoIncrementedPrimaryKey("id")
+        t.column("creationDate", .datetime)
+        t.column("name", .text)
+    }
+}
+```
+
+When you need to modify a table in a way that is not directly supported by SQLite, or not available on your target operating system, you will need to recreate the database table.
 
 For example:
 
@@ -181,13 +191,13 @@ You can make those migrations faster, but this requires a little care.
 
 **Your first mitigation technique is immediate foreign key checks.**
 
-When you register a migration with `.immediate` foreign key checks, the migration does not temporarily disable foreign keys, and does not need to perform a deferred full check of all foreign keys in ther database:
+When you register a migration with `.immediate` foreign key checks, the migration does not temporarily disable foreign keys, and does not need to perform a deferred full check of all foreign keys in the database:
 
 ```swift
-migrator.registerMigration("Faster migration", foreignKeyChecks: .immediate) { db in ... }
+migrator.registerMigration("Fast migration", foreignKeyChecks: .immediate) { db in ... }
 ```
 
-Such a migration is much faster, and it still guarantees database integrity. But it must only execute schema alterations directly supported by SQLite. Migrations that recreate tables as described in <doc:Migrations#Defining-the-Database-Schema-from-a-Migration> **must not** run with immediate foreign keys checks. You'll need to use the second mitigation technique:
+Such a migration is faster, and it still guarantees database integrity. But it must only execute schema alterations directly supported by SQLite. Migrations that recreate tables as described in <doc:Migrations#Defining-the-Database-Schema-from-a-Migration> **must not** run with immediate foreign keys checks. You'll need to use the second mitigation technique:
 
 **Your second mitigation technique is to disable deferred foreign key checks.**
 
@@ -197,22 +207,27 @@ You can ask the migrator to stop performing foreign key checks for all newly reg
 migrator = migrator.disablingDeferredForeignKeyChecks()
 ```
 
-> Warning: When deferred foreign key checks are disabled, your app becomes responsible for preventing foreign key violations from being committed to disk!
+Migrations become unchecked by default, and run faster. But your app becomes responsible for preventing foreign key violations from being committed to disk:
+
+```swift
+migrator = migrator.disablingDeferredForeignKeyChecks()
+migrator.registerMigration("Fast but unchecked migration") { db in ... }
+```
 
-In order to prevent foreign key violations from being committed to disk, you can:
+To prevent a migration from committing foreign key violations on disk, you can:
 
-- Register migrations with immediate foreign key checks, as long as they do not recreate tables as described in <doc:Migrations#Defining-the-Database-Schema-from-a-Migration>:
+- Register the migration with immediate foreign key checks, as long as it does not recreate tables as described in <doc:Migrations#Defining-the-Database-Schema-from-a-Migration>:
 
     ```swift
     migrator = migrator.disablingDeferredForeignKeyChecks()
-    migrator.registerMigration("Checked migration", foreignKeyChecks: .immediate) { db in ... }
+    migrator.registerMigration("Fast and checked migration", foreignKeyChecks: .immediate) { db in ... }
     ```
 
 - Perform foreign key checks on some tables only, before the migration is committed on disk:
 
     ```swift
     migrator = migrator.disablingDeferredForeignKeyChecks()
-    migrator.registerMigration("Partially checked migration") { db in
+    migrator.registerMigration("Partially checked") { db in
         ...
         
         // Throws an error and stops migrations if there exists a
diff --git a/GRDB/Documentation.docc/SQLSupport.md b/GRDB/Documentation.docc/SQLSupport.md
@@ -2,6 +2,64 @@
 
 SQL is the fundamental language for accessing SQLite databases.
 
+## Overview
+
+This section of the documentation focuses on low-level SQLite concepts: the SQL language, prepared statements, database rows and values.
+
+If SQL is not your cup of tea, jump to <doc:QueryInterface>.
+
+## SQL Support
+
+GRDB has a wide support for SQL. You can execute raw SQL statements:
+
+```swift
+try dbQueue.write { db in
+    try db.execute(sql: """
+        INSERT INTO player (name, score) VALUES (?, ?);
+        INSERT INTO player (name, score) VALUES (?, ?);
+        """, arguments: ["Arthur", 500, "Barbara", 1000])
+}
+```
+
+You can build prepared statements and lazily iterate fetched rows with great performances:
+
+```swift
+try dbQueue.read { db in
+    let sql = "SELECT id, score FROM player WHERE name = ?"  
+    let statement = try db.makeStatement(sql: sql)
+    let rows = try Row.fetchCursor(statement, arguments: ["O'Brien"])
+    while let row = try rows.next() {
+        let id: Int64 = row[0]
+        let score: Int = row[1]
+    }
+}
+```
+
+And you can leverage ``SQLRequest`` and ``FetchableRecord`` for defining streamlined apis with powerful SQL interpolation features:
+
+```swift
+struct Player: Decodable {
+    var id: Int64
+    var name: String
+    var score: Int
+}
+
+extension Player: FetchableRecord {
+    static func filter(name: String) -> SQLRequest<Player> {
+        "SELECT * FROM player WHERE name = \(name)"
+    }
+
+    static func maximumScore() -> SQLRequest<Int> {
+        "SELECT MAX(score) FROM player"
+    }
+}
+
+try dbQueue.read { db in
+    let players = try Player.filter(name: "O'Reilly").fetchAll(db) // [Player]
+    let maxScore = try Player.maximumScore().fetchOne(db)          // Int?
+}
+```
+
 ## Topics
 
 ### Fundamental Database Types
@@ -13,9 +71,9 @@ SQL is the fundamental language for accessing SQLite databases.
 
 ### SQL Literals and Requests
 
-- ``databaseQuestionMarks(count:)``
 - ``SQL``
 - ``SQLRequest``
+- ``databaseQuestionMarks(count:)``
 
 ### Database Values
 
diff --git a/GRDB/Record/MutablePersistableRecord.swift b/GRDB/Record/MutablePersistableRecord.swift
