Relocate DatabaseSnapshot documentation

Author: groue

GRDB/Core/DatabasePool.swift

@@ -6,19 +6,37 @@ import UIKit
 
 /// A database connection that allows concurrent accesses to an SQLite database.
 ///
-/// Unless ``Configuration/readonly``, a database pool opens an SQLite database
+/// ## Overview
+///
+/// Unless ``Configuration/readonly``, a `DatabasePool` opens an SQLite database
 /// in the [WAL mode](https://sqlite.org/wal.html).
 ///
 /// It creates one writer SQLite connection, and a pool of up to
 /// ``Configuration/maximumReaderCount`` read-only SQLite connections. All
 /// write accesses are executed in a serial **writer dispatch queue**. All
 /// read accesses are executed in **reader dispatch queues** (one per read-only
-/// SQLite connection).
+/// SQLite connection). SQLite connections are closed when the `DatabasePool`
+/// is deallocated.
 ///
 /// See <doc:Concurrency> for more information about concurrent
 /// database accesses.
 ///
-/// A database pool inherits most of its database access methods from the
+/// ## Usage
+///
+/// ```swift
+/// let dbPool = try DatabasePool(path: "/path/to/database.sqlite")
+///
+/// let playerCount = try dbPool.read { db in
+///     try Player.fetchCount(db)
+/// }
+///
+/// let newPlayerCount = try dbPool.write { db -> Int in
+///     try Player(name: "Arthur").insert(db)
+///     return try Player.fetchCount(db)
+/// }
+/// ```
+///
+/// `DatabasePool` inherits most of its database access methods from the
 /// ``DatabaseReader`` and ``DatabaseWriter`` protocols. It defines a few
 /// specific database access methods as well.
 ///
@@ -817,37 +835,15 @@ extension DatabasePool {
     /// The returned snapshot sees an unchanging database content, as it existed
     /// at the moment it was created.
     ///
-    /// When you want to control the latest committed changes seen by a
-    /// snapshot, create it from the pool's writer dispatch queue. Compare:
+    /// It is a programmer error to create a snapshot from the writer dispatch
+    /// queue when a transaction is opened:
     ///
     /// ```swift
-    /// let snapshot1 = try dbPool.writeWithoutTransaction { db -> DatabaseSnapshot in
+    /// try dbPool.write { db in
     ///     try Player.deleteAll()
-    ///     return try dbPool.makeSnapshot()
-    /// }
-    /// // <- Other threads may modify the database here
-    /// let snapshot2 = try dbPool.makeSnapshot()
-    ///
-    /// try snapshot1.read { db in
-    ///     // Guaranteed to be zero
-    ///     try Player.fetchCount(db)
-    /// }
-    ///
-    /// try snapshot2.read { db in
-    ///     // Could be anything
-    ///     try Player.fetchCount(db)
-    /// }
-    /// ```
-    ///
-    /// It is forbidden to create a snapshot from the writer dispatch queue when
-    /// a transaction is opened, because it is likely a programmer error:
     ///
-    /// ```swift
-    /// try dbPool.writeInTransaction { db in
-    ///     try Player.deleteAll()
     ///     // fatal error: makeSnapshot() must not be called from inside a transaction
     ///     let snapshot = try dbPool.makeSnapshot()
-    ///     return .commit
     /// }
     /// ```
     ///
@@ -868,11 +864,6 @@ extension DatabasePool {
     ///     let snapshot = try dbPool.makeSnapshot()
     /// }
     /// ```
-    ///
-    /// You can create as many snapshots as you need, regardless of the maximum
-    /// number of reader connections in the pool.
-    ///
-    /// Related SQLite documentation: <https://sqlite.org/isolation.html>
     public func makeSnapshot() throws -> DatabaseSnapshot {
         // Sanity check
         if writer.onValidQueue {

GRDB/Core/DatabaseQueue.swift

@@ -6,10 +6,28 @@ import UIKit
 
 /// A database connection that serializes accesses to an SQLite database.
 ///
-/// A database queue creates one single SQLite connection. All database accesses
-/// are executed in a serial **writer dispatch queue**.
+/// ## Overview
 ///
-/// A database queue inherits most of its database access methods from the
+/// A `DatabaseQueue` creates one single SQLite connection. All database
+/// accesses are executed in a serial **writer dispatch queue**. The SQLite
+/// connection is closed when the `DatabaseQueue` is deallocated.
+///
+/// ```swift
+/// let dbQueue = try DatabaseQueue(path: "/path/to/database.sqlite")
+///
+/// let playerCount = try dbQueue.read { db in
+///     try Player.fetchCount(db)
+/// }
+///
+/// let newPlayerCount = try dbQueue.write { db -> Int in
+///     try Player(name: "Arthur").insert(db)
+///     return try Player.fetchCount(db)
+/// }
+/// ```
+///
+/// ## Usage
+///
+/// `DatabaseQueue` inherits most of its database access methods from the
 /// ``DatabaseReader`` and ``DatabaseWriter`` protocols. It defines a few
 /// specific database access methods as well.
 /// 

GRDB/Core/DatabaseReader.swift

@@ -21,17 +21,17 @@ import Dispatch
 ///
 /// ### Reading from the Database
 ///
-/// - ``asyncRead(_:)``
 /// - ``read(_:)-3806d``
 /// - ``read(_:)-4w6gy``
 /// - ``readPublisher(receiveOn:value:)``
+/// - ``asyncRead(_:)``
 ///
 /// ### Unsafe Methods
 ///
-/// - ``asyncUnsafeRead(_:)``
 /// - ``unsafeRead(_:)-5i7tf``
 /// - ``unsafeRead(_:)-11mk0``
 /// - ``unsafeReentrantRead(_:)``
+/// - ``asyncUnsafeRead(_:)``
 ///
 /// ### Other Database Operations
 ///

GRDB/Core/DatabaseSnapshot.swift

@@ -3,16 +3,64 @@ import Dispatch
 /// A database connection that sees an unchanging database content, as it
 /// existed at the moment it was created.
 ///
+/// ## Overview
+///
+/// A `DatabaseSnapshot` creates one single SQLite connection. All database
+/// accesses are executed in a serial **reader dispatch queue**. The SQLite
+/// connection is closed when the `DatabaseSnapshot` is deallocated.
+///
+/// `DatabaseSnapshot` never sees any database modification during all its
+/// lifetime, and yet it doesn't prevent database updates. This "magic" is made
+/// possible by SQLite's WAL mode. See
+/// [Isolation In SQLite](https://sqlite.org/isolation.html) for
+/// more information.
+///
+/// ## Usage
+///
 /// You create instances of `DatabaseSnapshot` from a ``DatabasePool``, with
-/// ``DatabasePool/makeSnapshot()``.
+/// ``DatabasePool/makeSnapshot()``. The number of snapshots is unlimited,
+/// regardless of the ``Configuration/maximumReaderCount`` configuration:
+///
+/// ```swift
+/// let dbPool = try DatabasePool(path: "/path/to/database.sqlite")
+/// let snapshot = try dbPool.makeSnapshot()
+/// let playerCount = try snapshot.read { db in
+///     try Player.fetchCount(db)
+/// }
+/// ```
+///
+/// When you want to control the database state seen by a snapshot,
+/// create the snapshot from within a write access, outside of any transaction.
+///
+/// For example, compare the two snapshots below. The first one is guaranteed to
+/// see an empty table of players, because is is created after all players have
+/// been deleted, and from the serialized writer dispatch queue which prevents
+/// any concurrent write. The second is created without this concurrency
+/// protection, which means that some other threads may already have created
+/// some players:
+///
+/// ```swift
+/// let snapshot1 = try dbPool.writeWithoutTransaction { db -> DatabaseSnapshot in
+///     try db.inTransaction {
+///         try Player.deleteAll()
+///         return .commit
+///     }
+///
+///     return dbPool.makeSnapshot()
+/// }
+///
+/// // <- Other threads may have created some players here
+/// let snapshot2 = try dbPool.makeSnapshot()
 ///
-/// A database snapshot creates one single SQLite connection. All database
-/// accesses are executed in a serial dispatch queue.
+/// // Guaranteed to be zero
+/// let count1 = try snapshot1.read(Player.fetchCount)
 ///
-/// A database snapshot inherits all of its database access methods from the
-/// ``DatabaseReader`` protocol.
+/// // Could be anything
+/// let count2 = try snapshot2.read(Player.fetchCount)
+/// ```
 ///
-/// Related SQLite documentation: <https://sqlite.org/isolation.html>
+/// `DatabaseSnapshot` inherits its database access methods from the
+/// ``DatabaseReader`` protocols.
 public final class DatabaseSnapshot {
     private let serializedDatabase: SerializedDatabase
 

GRDB/Core/DatabaseWriter.swift

@@ -21,26 +21,26 @@ import Dispatch
 ///
 /// ### Writing into the Database
 ///
-/// - ``asyncWrite(_:completion:)``
-/// - ``asyncWriteWithoutTransaction(_:)``
 /// - ``write(_:)-76inz``
 /// - ``write(_:)-88g7e``
 /// - ``writePublisher(receiveOn:updates:)``
 /// - ``writePublisher(receiveOn:updates:thenRead:)``
 /// - ``writeWithoutTransaction(_:)-4qh1w``
 /// - ``writeWithoutTransaction(_:)-tckw``
-///
-/// ### Reading from the Database
-///
-/// - ``concurrentRead(_:)``
-/// - ``spawnConcurrentRead(_:)``
-/// - ``DatabaseFuture``
+/// - ``asyncWrite(_:completion:)``
+/// - ``asyncWriteWithoutTransaction(_:)``
 ///
 /// ### Exclusive Access to the Database
 ///
-/// - ``asyncBarrierWriteWithoutTransaction(_:)``
 /// - ``barrierWriteWithoutTransaction(_:)-280j1``
 /// - ``barrierWriteWithoutTransaction(_:)-7u4xw``
+/// - ``asyncBarrierWriteWithoutTransaction(_:)``
+///
+/// ### Reading from the Latest Committed Database State
+///
+/// - ``concurrentRead(_:)``
+/// - ``spawnConcurrentRead(_:)``
+/// - ``DatabaseFuture``
 ///
 /// ### Observing Database Transactions
 ///

GRDB/Documentation.docc/Concurrency.md

@@ -334,53 +334,6 @@ In the illustration below, the striped band shows the delay needed for the readi
 
 Types that conform to ``TransactionObserver`` can also use those methods in their ``TransactionObserver/databaseDidCommit(_:)`` method, in order to process database changes without blocking other threads that want to write into the database.
 
-## Database Snapshots
-
-**``DatabasePool`` can take snapshots.** A database snapshot sees an unchanging database content, as it existed at the moment it was created.
-
-"Unchanging" means that a snapshot never sees any database modifications during all its lifetime. And yet it doesn't prevent database updates. This "magic" is made possible by SQLite's WAL mode (see [Isolation In SQLite](https://sqlite.org/isolation.html)).
-
-```swift
-let snapshot = try dbPool.makeSnapshot()
-```
-
-You can create as many snapshots as you need, regardless of the maximum number of readers defined by the ``Configuration/maximumReaderCount`` configuration. A snapshot connection is closed when the snapshot is deallocated.
-
-**A snapshot can be used from any thread.** It has the same database access methods as database queues and pools, defined by the ``DatabaseReader`` protocol:
-
-```swift
-let playerCount = try snapshot.read { db in
-    try Player.fetchCount(db)
-}
-```
-
-When you want to control the latest committed changes seen by a snapshot, create the snapshot from within a write, outside of any transaction:
-
-```swift
-let snapshot1 = try dbPool.writeWithoutTransaction { db -> DatabaseSnapshot in
-    try db.inTransaction {
-        // delete all players
-        try Player.deleteAll()
-        return .commit
-    }
-    
-    // <- not in a transaction here
-    return dbPool.makeSnapshot()
-}
-// <- Other threads may modify the database here
-let snapshot2 = try dbPool.makeSnapshot()
-
-try snapshot1.read { db in
-    // Guaranteed to be zero
-    try Player.fetchCount(db)
-}
-
-try snapshot2.read { db in
-    // Could be anything
-    try Player.fetchCount(db)
-}
-```
-
 ## Topics
 
 ### Database Connections with Concurrency Guarantees