DocC: SQL

Author: groue

GRDB/Core/FetchRequest.swift

@@ -2,6 +2,26 @@
 
 /// A type that fetches and decodes database rows.
 ///
+/// The main kinds of fetch requests are ``SQLRequest``
+/// and ``QueryInterfaceRequest``:
+///
+/// ```swift
+/// let lastName = "O'Reilly"
+///
+/// // SQLRequest
+/// let request: SQLRequest<Player> = """
+///     SELECT * FROM player WHERE lastName = \(lastName)
+///     """
+///
+/// // QueryInterfaceRequest
+/// let request = Player.filter(Column("lastName") == lastName)
+///
+/// // Use the request
+/// try dbQueue.read { db in
+///     let players = try request.fetchAll(db) // [Player]
+/// }
+/// ```
+///
 /// ## Topics
 ///
 /// ### Counting the Results

GRDB/Core/SQLRequest.swift

@@ -4,14 +4,19 @@
 /// without any risk of syntax errors or SQL injection:
 ///
 /// ```swift
-/// extension Player {
+/// 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'Brien").fetchAll(db)
+///     let players = try Player.filter(name: "O'Brien").fetchAll(db) // [Player]
+///     let maxScore = Player.maximumScore().fetchOne(db)             // Int?
 /// }
 /// ```
 ///

GRDB/Core/Statement.swift

@@ -505,7 +505,47 @@ extension Statement {
 
 // MARK: - Cursors
 
-/// A cursor that iterates the result of a prepared ``Statement``.
+/// A cursor that lazily iterates the results of a prepared ``Statement``.
+///
+/// To get a `DatabaseCursor` instance, use a fetching method of
+/// ``Row``, ``DatabaseValueConvertible``, ``FetchableRecord``,
+/// or ``FetchRequest``. For example:
+///
+/// ```swift
+/// try dbQueue.read { db in
+///     // A cursor of database rows,
+///     // built from a prepared statement
+///     let statement = db.makeStatement(sql: "SELECT * FROM player")
+///     let rows = try Row.fetchCursor(statement)
+///     while let row = try rows.next() {
+///         let id: Int64 = row["id"]
+///         let name: String = row["name"]
+///     }
+///
+///     // A cursor of values,
+///     // built from an SQL string
+///     let scores = try Int.fetchCursor(db, sql: "SELECT score FROM player")
+///     while let score = try scores.next() {
+///         print(score)
+///     }
+///
+///     // A cursor of players,
+///     // built from a QueryInterfaceRequest:
+///     let request = Player.all()
+///     let players = try request.fetchCursor(db)
+///     while let player = try players.next() {
+///         print(player.name, player.score)
+///     }
+/// }
+/// ```
+///
+/// A database cursor is valid only during the current database access (read or
+/// write). Do not store or escape a cursor for later use.
+///
+/// A database cursor resets its underlying prepared statement with
+/// [`sqlite3_reset`](https://www.sqlite.org/c3ref/reset.html) when the cursor
+/// is created, and when it is deallocated. Don't share the same prepared
+/// statement between two cursors!
 public protocol DatabaseCursor: Cursor {
     /// Must be initialized to false.
     var _isDone: Bool { get set }

GRDB/Documentation.docc/SQLSupport.md

@@ -4,29 +4,26 @@ SQL is the fundamental language for accessing SQLite databases.
 
 ## Topics
 
-### Prepared Statements
+### Fundamental Database Types
 
 - ``Statement``
-
-### Database Rows
-
 - ``Row``
-
-### Database Values
-
-- ``DatabaseDateComponents``
 - ``DatabaseValue``
-- ``DatabaseValueConvertible``
-- ``StatementColumnConvertible``
+- ``DatabaseCursor``
 
 ### SQL Literals and Requests
 
 - ``databaseQuestionMarks(count:)``
 - ``SQL``
 - ``SQLRequest``
-- ``FetchRequest``
 
-### Cursors
+### Database Values
+
+- ``DatabaseDateComponents``
+- ``DatabaseValueConvertible``
+- ``StatementColumnConvertible``
+
+### Supporting Types
 
 - ``Cursor``
-- ``DatabaseCursor``
+- ``FetchRequest``