Documentation

GRDB/QueryInterface/DatabasePromise.swift

@@ -42,7 +42,6 @@ struct DatabasePromise<T> {
         }
     }
     
-    // TODO: write human-readable documentation for this classic monadic operation
     func flatMap<U>(_ transform: @escaping (T) -> DatabasePromise<U>) -> DatabasePromise<U> {
         return DatabasePromise<U> { db in
             try transform(self.resolve(db)).resolve(db)

GRDB/QueryInterface/QueryInterfaceRequest.swift

@@ -1,24 +1,32 @@
-/// QueryInterfaceRequest is the type of requests generated by TableRecord:
+// QueryInterfaceRequest is the type of requests generated by TableRecord:
+//
+//     struct Player: TableRecord { ... }
+//     let playerRequest = Player.all() // QueryInterfaceRequest<Player>
+//
+// It wraps an SQLSelectQuery, and has an attached type.
+//
+// The attached type helps decoding raw database values:
+//
+//     try dbQueue.read { db in
+//         try playerRequest.fetchAll(db) // [Player]
+//     }
+//
+// The attached type also helps the compiler validate associated requests:
+//
+//     playerRequest.including(required: Player.team) // OK
+//     fruitRequest.including(required: Player.team)  // Does not compile
+
+/// QueryInterfaceRequest is a request that generates SQL for you.
 ///
-///     struct Player: TableRecord { ... }
-///     let playerRequest = Player.all() // QueryInterfaceRequest<Player>
-///
-/// It wraps an SQLSelectQuery, and has an attached type.
-///
-/// The attached type helps decoding raw database values:
+/// For example:
 ///
 ///     try dbQueue.read { db in
-///         try playerRequest.fetchAll(db) // [Player]
-///         try playerRequest.asRequest(of: Row.self).fetchAll(db) // [Row]
+///         let request = Player
+///             .filter(Column("score") > 1000)
+///             .order(Column("name"))
+///         let players = try request.fetchAll(db) // [Player]
 ///     }
 ///
-/// The attached type also helps the compiler validate associated requests:
-///
-///     playerRequest.including(required: Player.team) // OK
-///     fruitRequest.including(required: Player.team)  // Does not compile
-
-/// A QueryInterfaceRequest describes an SQL query.
-///
 /// See https://github.com/groue/GRDB.swift#the-query-interface
 public struct QueryInterfaceRequest<T> {
     var query: SQLSelectQuery