SWIFT-340 Add missing documentation (#223)

Author: kmahar

Sources/MongoSwift/BSON/Document+Sequence.swift

@@ -30,13 +30,11 @@ extension Document: Sequence {
     }
 
     /**
-     * Returns a new document containing the keys of this document with the values transformed by
-     * the given closure.
+     * Returns a new document containing the keys of this document with the values transformed by the given closure.
      *
      * - Parameters:
-     *   - transform: A closure that transforms a `BSONValue`. `transform` accepts each value of the
-     *                document as its parameter and returns a transformed `BSONValue` of the same or
-     *                of a different type.
+     *   - transform: A closure that transforms a `BSONValue`. `transform` accepts each value of the document as its
+     *                parameter and returns a transformed `BSONValue` of the same or of a different type.
      *
      * - Returns: A document containing the keys and transformed values of this document.
      *
@@ -50,6 +48,14 @@ extension Document: Sequence {
         return output
     }
 
+    /**
+     * Returns a document containing all but the given number of initial key-value pairs.
+     *
+     * - Parameters:
+     *   - k: The number of key-value pairs to drop from the beginning of the document. k must be > 0.
+     *
+     * - Returns: A document starting after the specified number of key-value pairs.
+     */
     public func dropFirst(_ n: Int) -> Document {
         switch n {
         case ..<0:
@@ -64,6 +70,14 @@ extension Document: Sequence {
         }
     }
 
+    /**
+     * Returns a document containing all but the given number of final key-value pairs.
+     *
+     * - Parameters:
+     *   - k: The number of key-value pairs to drop from the end of the document. Must be greater than or equal to zero.
+     *
+     * - Returns: A document leaving off the specified number of final key-value pairs.
+     */
     public func dropLast(_ n: Int) -> Document {
         switch n {
         case ..<0:
@@ -78,6 +92,17 @@ extension Document: Sequence {
         }
     }
 
+    /**
+     * Returns a document by skipping the initial, consecutive key-value pairs that satisfy the given predicate.
+     *
+     * - Parameters:
+     *   - predicate: A closure that takes a key-value pair as its argument and returns a boolean indicating whether
+     *                the key-value pair should be included in the result.
+     *
+     * - Returns: A document starting after the initial, consecutive key-value pairs that satisfy `predicate`.
+     *
+     * - Throws: An error if `predicate` throws an error.
+     */
     public func drop(while predicate: (KeyValuePair) throws -> Bool) rethrows -> Document {
         // tracks whether we are still in a "dropping" state. once we encounter
         // an element that doesn't satisfy the predicate, we stop dropping.
@@ -97,6 +122,14 @@ extension Document: Sequence {
         }
     }
 
+    /**
+     * Returns a document, up to the specified maximum length, containing the initial key-value pairs of the document.
+     *
+     * - Parameters:
+     *   - maxLength: The maximum length for the returned document. Must be greater than or equal to zero.
+     *
+     * - Returns: A document starting at the beginning of this document with at most `maxLength` key-value pairs.
+     */
     public func prefix(_ maxLength: Int) -> Document {
         switch maxLength {
         case ..<0:
@@ -109,6 +142,17 @@ extension Document: Sequence {
         }
     }
 
+    /**
+     * Returns a document containing the initial, consecutive key-value pairs that satisfy the given predicate.
+     *
+     * - Parameters:
+     *   - predicate: A closure that takes a key-value pair as its argument and returns a boolean indicating whether
+     *                the key-value pair should be included in the result.
+     *
+     * - Returns: A document containing the initial, consecutive key-value pairs that satisfy `predicate`.
+     *
+     * - Throws: An error if `predicate` throws an error.
+     */
     public func prefix(while predicate: (KeyValuePair) throws -> Bool) rethrows -> Document {
         var output = Document()
         for elt in self {
@@ -118,6 +162,14 @@ extension Document: Sequence {
         return output
     }
 
+    /**
+     * Returns a document, up to the specified maximum length, containing the final key-value pairs of the document.
+     *
+     * - Parameters:
+     *   - maxLength: The maximum length for the returned document. Must be greater than or equal to zero.
+     *
+     * - Returns: A document ending at the end of this document with at most `maxLength` key-value pairs.
+     */
     public func suffix(_ maxLength: Int) -> Document {
         switch maxLength {
         case ..<0:
@@ -131,6 +183,26 @@ extension Document: Sequence {
         }
     }
 
+    /**
+     * Returns the longest possible subsequences of the document, in order, that don’t contain key-value pairs
+     * satisfying the given predicate. Key-value pairs that are used to split the document are not returned as part of
+     * any subsequence.
+     *
+     * - Parameters:
+     *   - maxSplits: The maximum number of times to split the document, or one less than the number of subsequences to
+     *                return. If `maxSplits` + 1 subsequences are returned, the last one is a suffix of the original 
+     *                document containing the remaining key-value pairs. `maxSplits` must be greater than or equal to
+     *                zero. The default value is `Int.max`.
+     *   - omittingEmptySubsequences: If false, an empty document is returned in the result for each pair of 
+     *                                consecutive key-value pairs satisfying the `isSeparator` predicate and for each
+     *                                key-value pair at the start or end of the document satisfying the `isSeparator` 
+     *                                predicate. If true, only nonempty documents are returned. The default value is
+     *                                true.
+     *   - isSeparator: A closure that returns true if its argument should be used to split the document and otherwise
+     *                  returns false.
+     *
+     * - Returns: An array of documents, split from this document's key-value pairs.
+     */ 
     public func split(maxSplits: Int = Int.max,
                       omittingEmptySubsequences: Bool = true,
                       whereSeparator isSeparator: (KeyValuePair) throws -> Bool) rethrows -> [Document] {
@@ -158,13 +230,13 @@ extension Document {
     // this variant is called by default, but the other is still accessible by explicitly stating
     // return type: `let newDocPairs: [Document.KeyValuePair] = newDoc.filter { ... }`
     /**
-     * Returns a new document containing the key-value pairs of the dictionary that satisfy the given predicate.
+     * Returns a new document containing the elements of the document that satisfy the given predicate.
      *
      * - Parameters:
      *   - isIncluded: A closure that takes a key-value pair as its argument and returns a `Bool` indicating whether
      *                 the pair should be included in the returned document.
      *
-     * - Returns: A document of the key-value pairs that `isIncluded` allows.
+     * - Returns: A document containing the key-value pairs that `isIncluded` allows.
      *
      * - Throws: An error if `isIncluded` throws an error.
      */

Sources/MongoSwift/BSON/Document.swift

@@ -20,6 +20,7 @@ public class DocumentStorage {
         self.pointer = bson_copy(pointer)
     }
 
+    /// Cleans up internal state.
     deinit {
         guard let pointer = self.pointer else {
             return

Sources/MongoSwift/ClientSession.swift

@@ -10,7 +10,7 @@ public class ClientSession: Encodable {
     internal init() {
     }
 
-    /// Clean up the internal mongoc_session_t.
+    /// Cleans up internal state.
     deinit {
     }
 

Sources/MongoSwift/MongoClient.swift

@@ -227,9 +227,7 @@ public class MongoClient {
         self.decoder = BSONDecoder()
     }
 
-    /**
-     * Cleans up the internal `mongoc_client_t`.
-     */
+    /// Cleans up internal state.
     deinit {
         close()
     }

Sources/MongoSwift/MongoCollection+BulkWrite.swift

@@ -357,6 +357,7 @@ public class BulkWriteOperation {
         return self.isAcknowledged ? result : nil
     }
 
+    /// Cleans up internal state.
     deinit {
         guard let bulk = self.bulk else {
             return

Sources/MongoSwift/MongoCollection+FindAndModify.swift

@@ -383,6 +383,7 @@ private class FindAndModifyOptions {
         }
     }
 
+    /// Cleans up internal state.
     deinit {
         guard let options = self._options else {
             return

Sources/MongoSwift/MongoCollection.swift

@@ -61,7 +61,7 @@ public class MongoCollection<T: Codable> {
         self.decoder = withDecoder
     }
 
-    /// Deinitializes a `MongoCollection`, cleaning up the internal `mongoc_collection_t`
+    /// Cleans up internal state.
     deinit {
         guard let collection = self._collection else {
             return

Sources/MongoSwift/MongoCursor.swift

@@ -38,7 +38,7 @@ public class MongoCursor<T: Codable>: Sequence, IteratorProtocol {
         }
     }
 
-    /// Deinitializes a `MongoCursor`, cleaning up the internal `mongoc_cursor_t`.
+    /// Cleans up internal state.
     deinit {
         self.close()
     }

Sources/MongoSwift/MongoDatabase.swift

@@ -241,7 +241,7 @@ public class MongoDatabase {
         self.decoder = decoder
     }
 
-    /// Deinitializes a MongoDatabase, cleaning up the internal `mongoc_database_t`.
+    /// Cleans up internal state.
     deinit {
         guard let database = self._database else {
             return

Sources/MongoSwift/ReadConcern.swift

@@ -86,7 +86,7 @@ public class ReadConcern: Codable {
         try container.encodeIfPresent(self.level, forKey: .level)
     }
 
-    /// Cleans up the internal `mongoc_read_concern_t`.
+    /// Cleans up internal state.
     deinit {
         guard let readConcern = self._readConcern else {
             return