Documentation organization

Author: groue

GRDB/Core/Database.swift

@@ -69,7 +69,6 @@ let SQLITE_TRANSIENT = unsafeBitCast(OpaquePointer(bitPattern: -1), to: sqlite3_
 /// - ``add(transactionObserver:extent:)``
 /// - ``afterNextTransaction(onCommit:onRollback:)``
 /// - ``remove(transactionObserver:)``
-/// - ``TransactionObservationExtent``
 ///
 /// ### Collations
 ///

GRDB/Core/DatabaseWriter.swift

@@ -3,7 +3,7 @@ import Combine
 #endif
 import Dispatch
 
-/// A type that write into an SQLite database.
+/// A type that writes into an SQLite database.
 ///
 /// Do not declare new conformances to `DatabaseWriter`. Only the
 /// ``DatabaseQueue`` and ``DatabasePool`` types are valid conforming types.

GRDB/Core/TransactionObserver.swift

@@ -93,9 +93,7 @@ extension Database {
             extent: .nextTransaction)
     }
 
-    /// The extent of a transaction observation.
-    ///
-    /// See ``Database/add(transactionObserver:extent:)``.
+    /// The extent of the observation performed by a ``TransactionObserver``.
     public enum TransactionObservationExtent {
         /// Observation lasts until observer is deallocated.
         case observerLifetime
@@ -726,7 +724,7 @@ class DatabaseObservationBroker {
 /// ``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
+/// All observer methods are called in the writer dispatch queue, serialized
 /// with all database updates (see ``DatabaseWriter``).
 ///
 /// Some changes and transactions are not notified:

GRDB/Documentation.docc/Concurrency.md

@@ -342,6 +342,11 @@ Types that conform to ``TransactionObserver`` can also use those methods in thei
 - ``DatabaseReader``
 - ``DatabaseWriter``
 
+### Advanced Concurrency
+
+- <doc:DatabaseSharing>
+
+
 [demo apps]: https://github.com/groue/GRDB.swift/tree/master/Documentation/DemoApps
 [`SQLITE_BUSY`]: https://www.sqlite.org/rescode.html#busy
 [RxGRDB]: https://github.com/RxSwiftCommunity/RxGRDB

GRDB/Documentation.docc/DatabaseObservation.md

@@ -1,6 +1,6 @@
 # Database Observation
 
-Observe database changes and transactions. 
+Observe database changes and transactions.
 
 ## Topics
 
@@ -13,7 +13,11 @@ Observe database changes and transactions.
 ### Observing Database Transactions
 
 - ``DatabaseRegionObservation``
+
+### Low-Level Transaction Observers
+
 - ``TransactionObserver``
+- ``Database/TransactionObservationExtent``
 
 ### Database Regions
 

GRDB/Documentation.docc/Documentation.md

@@ -19,6 +19,7 @@ GRDB provides raw access to SQL and advanced SQLite features, because one someti
 
 - <doc:DatabaseSchema>
 - <doc:Migrations>
+- <doc:SingleRowTables>
 
 ### Record Types and the Query Interface
 
@@ -30,13 +31,7 @@ GRDB provides raw access to SQL and advanced SQLite features, because one someti
 
 ### Full-Text Search
 
-- ``FTS3``
-- ``FTS4``
-
-### Database Techniques
-
-- <doc:DatabaseSharing>
-- <doc:SingleRowTables>
+- <doc:FullTextSearch>
 
 ### Combine Publishers
 

GRDB/Documentation.docc/FullTextSearch.md

@@ -0,0 +1,14 @@
+# Full-Text Search
+
+Search a corpus of textual documents.
+
+## Overview
+
+Please refer to the [Full-Text Search](https://github.com/groue/GRDB.swift/blob/master/Documentation/FullTextSearch.md) guide. It also describes how to enable support for the FTS5 engine.
+
+## Topics
+
+### Full-Text Engines
+
+- ``FTS3``
+- ``FTS4``

GRDB/Documentation.docc/SingleRowTables.md

@@ -65,7 +65,7 @@ It is not a good idea to populate the table in a migration, for two reasons:
 
 1. This migration is not a hard guarantee that the table will never be empty. As a consequence, this won't prevent the application code from dealing with the possibility of a missing row. On top of that, this application code may not use the same default values as the SQLite schema, with unclear consequences.
 
-2. Migrations that have been release on the users' devices should never change (see <doc:Migrations#Good-Practices-for-Defining-Migrations>). Inserting an initial row in a migration, makes it difficult for the application to adjust the sensible default values in a future version.
+2. Migrations that have been deployed on the users' devices should never change (see <doc:Migrations#Good-Practices-for-Defining-Migrations>). Inserting an initial row in a migration makes it difficult for the application to adjust the sensible default values in a future version.
 
 The recommended migration creates the table, nothing more:
 
@@ -150,25 +150,20 @@ if config.flag {
 
 // WRITE
 try dbQueue.write { db in
+    // Saves a new config in the database
     var config = try AppConfiguration.fetch(db)
-    
-    // Update some config values
     try config.updateChanges(db) {
         $0.flag = true
     }
 
-    // Other possible ways to write config:
-    try config.update(db)
+    // Other possible ways to save the config:
     try config.save(db)
+    try config.update(db)
     try config.insert(db)
     try config.upsert(db)
 }
 ```
 
-The ``MutablePersistableRecord/updateChanges(_:onConflict:modify:)`` method only updates the values changed by its closure argument (and performs an initial insert of default configuration if the database table is empty).
-
-The four `update`, `save`, `insert` and `upsert` methods can be used interchangeably. They all make sure the configuration is fully stored in the database.
-
 See ``MutablePersistableRecord`` for more information about persistence methods.