SWIFT-704 Update async docstrings to reflect error propagation (#394)

Author: kmahar

Sources/MongoSwift/ClientSession.swift

@@ -17,9 +17,10 @@ import NIO
  *   ```
  *   let opts = CollectionOptions(readConcern: ReadConcern(.majority), writeConcern: try WriteConcern(w: .majority))
  *   let collection = database.collection("mycoll", options: opts)
- *   try client.withSession { session in
- *       try collection.insertOne(["x": 1], session: session)
- *       try collection.find(["x": 1], session: session)
+ *   let futureCount = client.withSession { session in
+ *       collection.insertOne(["x": 1], session: session).flatMap { _ in
+ *           collection.countDocuments(session: session)
+ *       }
  *   }
  *   ```
  *

Sources/MongoSwift/ConnectionPool.swift

@@ -38,7 +38,7 @@ internal class ConnectionPool {
     /// Initializes the pool using the provided `ConnectionString`.
     internal init(from connString: ConnectionString, options: TLSOptions? = nil) throws {
         guard let pool = mongoc_client_pool_new(connString._uri) else {
-            throw InvalidArgumentError(message: "libmongoc not built with TLS support")
+            throw InternalError(message: "Failed to initialize libmongoc client pool")
         }
 
         guard mongoc_client_pool_set_error_api(pool, MONGOC_ERROR_API_VERSION_2) else {

Sources/MongoSwift/MongoClient.swift

@@ -242,8 +242,6 @@ public class MongoClient {
      *
      * - Throws:
      *   - A `InvalidArgumentError` if the connection string passed in is improperly formatted.
-     *   - A `InvalidArgumentError` if the connection string specifies the use of TLS but libmongoc was not
-     *     built with TLS support.
      */
     public init(
         _ connectionString: String = "mongodb://localhost:27017",
@@ -303,7 +301,8 @@ public class MongoClient {
         }
     }
 
-    /// Starts a new `ClientSession` with the provided options.
+    /// Starts a new `ClientSession` with the provided options. When you are done using this session, you must call
+    /// `ClientSession.end()` on it.
     public func startSession(options: ClientSessionOptions? = nil) -> ClientSession {
         return ClientSession(client: self, options: options)
     }
@@ -312,8 +311,16 @@ public class MongoClient {
      * Starts a new `ClientSession` with the provided options and passes it to the provided closure.
      * The session is only valid within the body of the closure and will be ended after the body completes.
      *
-     * - Throws:
-     *   - `RuntimeError.compatibilityError` if the deployment does not support sessions.
+     * - Parameters:
+     *   - options: Options to use when creating the session.
+     *   - sessionBody: A closure which takes in a `ClientSession` and returns an `EventLoopFuture<T>`.
+     *
+     * - Returns:
+     *    An `EventLoopFuture<T>`, the return value of the user-provided closure.
+     *
+     *    If the future fails, the error is likely one of the following:
+     *    - `CompatibilityError` if the deployment does not support sessions.
+     *    - `LogicError` if this client has already been closed.
      */
     public func withSession<T>(
         options: ClientSessionOptions? = nil,
@@ -344,18 +351,21 @@ public class MongoClient {
     }
 
     /**
-     * Run the `listDatabases` command.
+     * Retrieves a list of databases in this client's MongoDB deployment.
      *
      * - Parameters:
      *   - filter: Optional `Document` specifying a filter that the listed databases must pass. This filter can be based
      *     on the "name", "sizeOnDisk", "empty", or "shards" fields of the output.
      *   - session: Optional `ClientSession` to use when executing this command.
      *
-     * - Returns: An `EventLoopFuture<[DatabaseSpecification]>` containing the databases matching provided criteria.
+     * - Returns:
+     *    An `EventLoopFuture<[DatabaseSpecification]>`. On success, the future contains an array of the specifications
+     *    of databases matching the provided criteria.
      *
-     * - Throws:
-     *   - `LogicError` if the provided session is inactive.
-     *   - `EncodingError` if an error is encountered while encoding the options to BSON.
+     *    If the future fails, the error is likely one of the following:
+     *    - `LogicError` if the provided session is inactive.
+     *    - `LogicError` if this client has already been closed.
+     *    - `EncodingError` if an error is encountered while encoding the options to BSON.
      *
      * - SeeAlso: https://docs.mongodb.com/manual/reference/command/listDatabases/
      */
@@ -373,16 +383,19 @@ public class MongoClient {
     }
 
     /**
-     * Get a list of `MongoDatabase`s.
+     * Get a list of `MongoDatabase`s corresponding to the databases in this client's MongoDB deployment.
      *
      * - Parameters:
      *   - filter: Optional `Document` specifying a filter on the names of the returned databases.
      *   - session: Optional `ClientSession` to use when executing this command
      *
-     * - Returns: An `EventLoopFuture<[MongoDatabase]>` containing databases that match the provided filter.
+     * - Returns:
+     *    An `EventLoopFuture<[MongoDatabase]>`. On success, the future contains an array of `MongoDatabase`s that
+     *    match the provided filter.
      *
-     * - Throws:
-     *   - `LogicError` if the provided session is inactive.
+     *    If the future fails, the error is likely one of the following:
+     *    - `LogicError` if the provided session is inactive.
+     *    - `LogicError` if this client has already been closed.
      */
     public func listMongoDatabases(
         _ filter: Document? = nil,
@@ -392,16 +405,19 @@ public class MongoClient {
     }
 
     /**
-     * Get a list of names of databases.
+     * Get the names of databases in this client's MongoDB deployment.
      *
      * - Parameters:
      *   - filter: Optional `Document` specifying a filter on the names of the returned databases.
      *   - session: Optional `ClientSession` to use when executing this command
      *
-     * - Returns: An `EventLoopFuture<[String]>` containing names of databases that match the provided filter.
+     * - Returns:
+     *    An `EventLoopFuture<[String]>`. On success, the future contains an array of names of databases that
+     *    match the provided filter.
      *
-     * - Throws:
-     *   - `LogicError` if the provided session is inactive.
+     *    If the future fails, the error is likely one of the following:
+     *    - `LogicError` if the provided session is inactive.
+     *    - `LogicError` if this client has already been closed.
      */
     public func listDatabaseNames(
         _ filter: Document? = nil,
@@ -426,7 +442,7 @@ public class MongoClient {
      *   - name: the name of the database to retrieve
      *   - options: Optional `DatabaseOptions` to use for the retrieved database
      *
-     * - Returns: a `MongoDatabase` corresponding to the provided database name
+     * - Returns: a `MongoDatabase` corresponding to the provided database name.
      */
     public func db(_ name: String, options: DatabaseOptions? = nil) -> MongoDatabase {
         return MongoDatabase(name: name, client: self, options: options)

Sources/MongoSwift/MongoCollection+BulkWrite.swift

@@ -11,15 +11,17 @@ extension MongoCollection {
      *   - options: optional `BulkWriteOptions` to use while executing the operation.
      *   - session: Optional `ClientSession` to use when executing this command
      *
-     * - Returns: an `EventLoopFuture` containing the `BulkWriteResult`, or containing `nil` if the write concern is
-     *            unacknowledged.
+     * - Returns:
+     *    An `EventLoopFuture<BulkWriteResult?>`. On success, the future contains either a `BulkWriteResult`, or
+     *    contains `nil` if the write concern is unacknowledged.
      *
-     * - Throws:
-     *   - `InvalidArgumentError` if `requests` is empty.
-     *   - `LogicError` if the provided session is inactive.
-     *   - `BulkWriteError` if any error occurs while performing the writes. This includes errors that would
-     *     typically be thrown as `RuntimeError`s or `CommandError`s elsewhere.
-     *   - `EncodingError` if an error occurs while encoding the `CollectionType` or the options to BSON.
+     *    If the future fails, the error is likely one of the following:
+     *    - `InvalidArgumentError` if `requests` is empty.
+     *    - `LogicError` if the provided session is inactive.
+     *    - `LogicError` if this collection's parent client has already been closed.
+     *    - `BulkWriteError` if any error occurs while performing the writes. This includes errors that would
+     *       typically be propagated as `RuntimeError`s or `CommandError`s elsewhere.
+     *    - `EncodingError` if an error occurs while encoding the `CollectionType` or the options to BSON.
      */
     public func bulkWrite(
         _ requests: [WriteModel<T>],

Sources/MongoSwift/MongoCollection+FindAndModify.swift

@@ -11,15 +11,17 @@ extension MongoCollection {
      *   - options: Optional `FindOneAndDeleteOptions` to use when executing the command
      *   - session: Optional `ClientSession` to use when executing this command
      *
-     * - Returns: An `EventLoopFuture` containing the deleted document, represented as a `CollectionType`, or
-     *            containing `nil` if no document was deleted.
+     * - Returns:
+     *    An `EventLoopFuture<CollectionType?>`. On success, contains either the deleted document, represented as a
+     *    `CollectionType`, or contains `nil` if no document was deleted.
      *
-     * - Throws:
-     *   - `InvalidArgumentError` if any of the provided options are invalid.
-     *   - `LogicError` if the provided session is inactive.
-     *   - `CommandError` if an error occurs that prevents the command from executing.
-     *   - `WriteError` if an error occurs while executing the command.
-     *   - `DecodingError` if the deleted document cannot be decoded to a `CollectionType` value.
+     *    If the future fails, the error is likely one of the following:
+     *    - `InvalidArgumentError` if any of the provided options are invalid.
+     *    - `LogicError` if the provided session is inactive.
+     *    - `LogicError` if this collection's parent client has already been closed.
+     *    - `CommandError` if an error occurs that prevents the command from executing.
+     *    - `WriteError` if an error occurs while executing the command.
+     *    - `DecodingError` if the deleted document cannot be decoded to a `CollectionType` value.
      */
     public func findOneAndDelete(
         _ filter: Document,
@@ -40,16 +42,19 @@ extension MongoCollection {
      *   - options: Optional `FindOneAndReplaceOptions` to use when executing the command
      *   - session: Optional `ClientSession` to use when executing this command
      *
-     * - Returns: An `EventLoopFuture` containing a `CollectionType`, representing either the original document or its
-     *            replacement, depending on selected options, or containing `nil` if there was no match.
+     * - Returns:
+     *    An `EventLoopFuture<CollectionType?>`. On success, contains a `CollectionType`, representing either the
+     *    original document or its replacement, depending on selected options; or containing `nil` if there was no
+     *    matching document.
      *
-     * - Throws:
-     *   - `InvalidArgumentError` if any of the provided options are invalid.
-     *   - `LogicError` if the provided session is inactive.
-     *   - `CommandError` if an error occurs that prevents the command from executing.
-     *   - `WriteError` if an error occurs while executing the command.
-     *   - `DecodingError` if the replaced document cannot be decoded to a `CollectionType` value.
-     *   - `EncodingError` if `replacement` cannot be encoded to a `Document`.
+     *    If the future fails, the error is likely one of the following:
+     *    - `InvalidArgumentError` if any of the provided options are invalid.
+     *    - `LogicError` if the provided session is inactive.
+     *    - `LogicError` if this collection's parent client has already been closed.
+     *    - `CommandError` if an error occurs that prevents the command from executing.
+     *    - `WriteError` if an error occurs while executing the command.
+     *    - `DecodingError` if the replaced document cannot be decoded to a `CollectionType` value.
+     *    - `EncodingError` if `replacement` cannot be encoded to a `Document`.
      */
     public func findOneAndReplace(
         filter: Document,
@@ -74,15 +79,17 @@ extension MongoCollection {
      *   - options: Optional `FindOneAndUpdateOptions` to use when executing the command
      *   - session: Optional `ClientSession` to use when executing this command
      *
-     * - Returns: An `EventLoopFuture` containing a `CollectionType` representing either the original or updated
-     *            document, depending on selected options, or containing `nil` if there was no match.
+     * - Returns:
+     *    An `EventLoopFuture<CollectionType>`. On success, contains either the original or updated document, depending
+     *    on selected options, or contains `nil` if there was no match.
      *
-     * - Throws:
-     *   - `InvalidArgumentError` if any of the provided options are invalid.
-     *   - `LogicError` if the provided session is inactive.
-     *   - `CommandError` if an error occurs that prevents the command from executing.
-     *   - `WriteError` if an error occurs while executing the command.
-     *   - `DecodingError` if the updated document cannot be decoded to a `CollectionType` value.
+     *    If the future fails, the error is likely one of the following:
+     *    - `InvalidArgumentError` if any of the provided options are invalid.
+     *    - `LogicError` if the provided session is inactive.
+     *    - `LogicError` if this collection's parent client has already been closed.
+     *    - `CommandError` if an error occurs that prevents the command from executing.
+     *    - `WriteError` if an error occurs while executing the command.
+     *    - `DecodingError` if the updated document cannot be decoded to a `CollectionType` value.
      */
     public func findOneAndUpdate(
         filter: Document,
@@ -96,12 +103,16 @@ extension MongoCollection {
     /**
      * A private helper method for findAndModify operations to use.
      *
-     * - Throws:
-     *   - `InvalidArgumentError` if any of the provided options are invalid.
-     *   - `LogicError` if the provided session is inactive.
-     *   - `CommandError` if an error occurs that prevents the command from executing.
-     *   - `WriteError` if an error occurs while executing the command.
-     *   - `DecodingError` if the updated document cannot be decoded to a `CollectionType` value.
+     * - Returns:
+     *    An `EventLoopFuture<CollectionType?>. On success, contains the document returned by the server, if one exists.
+     *
+     *    If the future fails, the error is likely one of the following:
+     *    - `InvalidArgumentError` if any of the provided options are invalid.
+     *    - `LogicError` if the provided session is inactive.
+     *    - `LogicError` if this collection's parent client has already been closed.
+     *    - `CommandError` if an error occurs that prevents the command from executing.
+     *    - `WriteError` if an error occurs while executing the command.
+     *    - `DecodingError` if the updated document cannot be decoded to a `CollectionType` value.
      */
     private func findAndModify(
         filter: Document,