CBL-5613: Swift API docs for Scope using Obj-c reference (#3284)

* fix obj-c ref in swift api

* fix some other mistakes or spacing within Swift API Docs

Swift/Collection.swift

@@ -39,7 +39,7 @@ import CouchbaseLiteSwift_Private
 /// - Cannot start with _ or %.
 /// - Both scope and collection names are case sensitive.
 ///
-/// ## CBLCollection Lifespan
+/// ## Collection Lifespan
 /// A `Collection` object and its reference remain valid until either
 /// the database is closed or the collection itself is deleted, in that case it will
 /// throw an NSError with the CBLError.notOpen code while accessing the collection APIs.

Swift/Database+Query.swift

@@ -24,7 +24,7 @@ extension Database : QueryFactory {
     /// Creates a Query object from the given query string.
     ///
     /// - Parameters:
-    ///     - query Query string
+    ///   - query: Query string.
     /// - Returns: A query created by the given query string.
     /// - Throws: An error on when the given query string is invalid.
     public func createQuery(_ query: String) throws -> Query {
@@ -53,8 +53,8 @@ extension Database : QueryFactory {
     /// will replace the old index. Creating the same index with the same name will be no-ops.
     ///
     /// - Parameters:
-    ///     - config: The index configuration
-    ///     - name: The index name.
+    ///   - config: The index configuration
+    ///   - name: The index name.
     /// - Throws: An error on a failure.
     @available(*, deprecated, message: "Use database.defaultCollection().createIndex(:name:) instead.")
     public func createIndex(_ config: IndexConfiguration, name: String) throws {

Swift/From.swift

@@ -87,8 +87,8 @@ public final class From: Query, JoinRouter, WhereRouter, GroupByRouter, OrderByR
         return self.limit(limit, offset: nil)
     }
 
-    ///  Creates and chains a Limit object to skip the returned results for the given offset
-    ///  position and to limit the number of results to not more than the given limit value.
+    /// Creates and chains a Limit object to skip the returned results for the given offset
+    /// position and to limit the number of results to not more than the given limit value.
     ///
     /// - Parameters:
     ///   - limit: The limit expression.

Swift/FullTextFunction.swift

@@ -36,8 +36,9 @@ public final class FullTextFunction {
 
     /// Creates a full-text match expression with the given full-text index name and the query text
     ///
-    /// - Parameter indexName: The index name.
-    /// - Parameter query: The query string.
+    /// - Parameters:
+    ///   - indexName: The index name.
+    ///   - query: The query string.
     /// - Returns: The full-text match function expression.
     @available(*, deprecated, message: "Use FullTextFunction.match(withIndex:query) instead.")
     public static func match(indexName: String, query: String) -> ExpressionProtocol {
@@ -59,10 +60,11 @@ public final class FullTextFunction {
         return QueryExpression(CBLQueryFullTextFunction.rank(withIndex: i.toImpl()))
     }
 
-    ///  Creates a full-text match() function  with the given full-text index expression and the query text
+    /// Creates a full-text match() function with the given full-text index expression and the query text
     ///
-    /// - Parameter index: The full-text index expression.
-    /// - Parameter query: The query string.
+    /// - Parameters:
+    ///   - indexName: TThe full-text index expression.
+    ///   - query: The query string.
     /// - Returns: The full-text match() function expression.
     public static func match(_ index: IndexExpressionProtocol, query: String) -> ExpressionProtocol {
         guard let i = index as? FullTextIndexExpression else {

Swift/Function.swift

@@ -259,7 +259,7 @@ public final class Function {
     /// Creates a TAN(expr) function that returns the tangent of the given numeric expression.
     ///
     /// - Parameter expression: The numeric expression.
-    /// - Returns:  The TAN(expr) function.
+    /// - Returns: The TAN(expr) function.
     public static func tan(_ expression: ExpressionProtocol) -> ExpressionProtocol {
         return QueryExpression(CBLQueryFunction.tan(expression.toImpl()))
     }

Swift/GroupBy.swift

@@ -58,8 +58,8 @@ public final class GroupBy: Query, HavingRouter, OrderByRouter, LimitRouter {
         return self.limit(limit, offset: nil)
     }
 
-    ///  Creates and chains a Limit object to skip the returned results for the given offset
-    ///  position and to limit the number of results to not more than the given limit value.
+    /// Creates and chains a Limit object to skip the returned results for the given offset
+    /// position and to limit the number of results to not more than the given limit value.
     ///
     /// - Parameters:
     ///   - limit: The limit expression.

Swift/Having.swift

@@ -48,8 +48,8 @@ public final class Having: Query, OrderByRouter, LimitRouter {
         return self.limit(limit, offset: nil)
     }
 
-    ///  Creates and chains a Limit object to skip the returned results for the given offset
-    ///  position and to limit the number of results to not more than the given limit value.
+    /// Creates and chains a Limit object to skip the returned results for the given offset
+    /// position and to limit the number of results to not more than the given limit value.
     ///
     /// - Parameters:
     ///   - limit: The limit expression.

Swift/Index.swift

@@ -28,6 +28,8 @@ public protocol Index { }
 /// A value index for regular queries.
 public final class ValueIndex: Index, CBLIndexConvertible {
 
+    // MARK: Internal
+
     private let impl: CBLIndex
 
     init(items: [ValueIndexItem]) {
@@ -135,12 +137,16 @@ public class FullTextIndexItem {
 
 protocol CBLIndexConvertible {
 
+    // MARK: Internal
+
     func toImpl() -> CBLIndex
 
 }
 
 extension Index {
 
+    // MARK: Internal
+
     func toImpl() -> CBLIndex {
         if let index = self as? CBLIndexConvertible {
             return index.toImpl()

Swift/IndexBuilder.swift

@@ -25,7 +25,7 @@ public class IndexBuilder {
     /// Create a value index with the given index items. The index items are a list of
     /// the properties or expressions to be indexed.
     ///
-    /// - Parameter: items The index items.
+    /// - Parameter items: The index items.
     /// - Returns: The ValueIndex.
     public static func valueIndex(items: ValueIndexItem...) -> ValueIndex {
         return valueIndex(items: items);
@@ -44,7 +44,7 @@ public class IndexBuilder {
     /// the index items are the properties that are used to perform the
     /// match operation against with.
     ///
-    /// - Parameter: items The index items.
+    /// - Parameter items: The index items.
     /// - Returns:  The FullTextIndex.
     public static func fullTextIndex(items: FullTextIndexItem...) -> FullTextIndex {
         return fullTextIndex(items: items)
@@ -54,7 +54,7 @@ public class IndexBuilder {
     /// the index items are the properties that are used to perform the
     /// match operation against with.
     ///
-    /// - Parameter: items The index items.
+    /// - Parameter items: The index items.
     /// - Returns:  The FullTextIndex.
     public static func fullTextIndex(items: [FullTextIndexItem]) -> FullTextIndex {
         return FullTextIndex(items: items)

Swift/Indexable.swift

@@ -27,7 +27,7 @@ public protocol Indexable {
     /// Create an index with the index name and config.
     func createIndex(withName name: String, config: IndexConfiguration) throws
 
-    /// Create an index with the index name and index. 
+    /// Create an index with the index and index name. 
     func createIndex(_ index: Index, name: String) throws;
 
     /// Delete an index by name.

Swift/Joins.swift

@@ -55,8 +55,8 @@ public final class Joins: Query, WhereRouter, OrderByRouter, LimitRouter {
         return self.limit(limit, offset: nil)
     }
 
-    ///  Creates and chains a Limit object to skip the returned results for the given offset
-    ///  position and to limit the number of results to not more than the given limit value.
+    /// Creates and chains a Limit object to skip the returned results for the given offset
+    /// position and to limit the number of results to not more than the given limit value.
     ///
     /// - Parameters:
     ///   - limit: The limit expression.

Swift/MutableDocument.swift

@@ -57,8 +57,7 @@ public final class MutableDocument : Document, MutableDictionaryProtocol {
 
     /// Initializes a new MutableDocument object with the JSON data.
     /// 
-    /// - Parameters:
-    ///   - json: The JSON string with data.
+    /// - Parameter json: The JSON string with data.
     /// - Throws: An error on a failure.
     public convenience init(json: String) throws {
         self.init(CBLMutableDocument())

Swift/OrderBy.swift

@@ -31,8 +31,8 @@ public final class OrderBy: Query, LimitRouter {
         return self.limit(limit, offset: nil)
     }
 
-    ///  Creates and chains a Limit object to skip the returned results for the given offset
-    ///  position and to limit the number of results to not more than the given limit value.
+    /// Creates and chains a Limit object to skip the returned results for the given offset
+    /// position and to limit the number of results to not more than the given limit value.
     ///
     /// - Parameters:
     ///   - limit: The limit expression.

Swift/Query.swift

@@ -154,16 +154,16 @@ public class Query {
     /// - Parameters:
     ///   - database: The database to query.
     ///   - json: JSON data encoding the query. This can be obtained from a Query object's
-    //            JSONRepresentation property.
+    ///           JSONRepresentation property.
     init(database: Database, JSONRepresentation json: Data) {
         self.database = database
         queryImpl = CBLQuery(database: database.impl, jsonRepresentation: json)
     }
 
     /// Creates a query, given the query string, as from the expression property.
     /// - Parameters:
-    ///     - database  The database to query.
-    ///     - expressions  String representing the query expression.
+    ///   - database: The database to query.
+    ///   - expressions: String representing the query expression.
     init(database: Database, expressions: String) throws {
         self.database = database
         queryImpl = try database.impl.createQuery(expressions)

Swift/QueryFactory.swift

@@ -23,8 +23,7 @@ import Foundation
 public protocol QueryFactory {
     /// Creates a Query object from the given query string.
     ///
-    /// - Parameters:
-    ///     - query Query string
+    /// - Parameter query: Query string
     /// - Returns: A query created by the given query string.
     /// - Throws: An error on when the given query string is invalid.
     func createQuery(_ query: String) throws -> Query

Swift/Replicator.swift

@@ -29,11 +29,12 @@ public final class Replicator {
 
     /// Activity level of a replicator.
     ///
-    /// - stopped: The replicator is finished or hit a fatal error.
-    /// - offline: The replicator is offline as the remote host is unreachable.
-    /// - connecting: The replicator is connecting to the remote host.
-    /// - idle: The replicator is inactive waiting for changes or offline.
-    /// - busy: The replicator is actively transferring data.
+    /// - Note:
+    ///   - stopped: The replicator is finished or hit a fatal error.
+    ///   - offline: The replicator is offline as the remote host is unreachable.
+    ///   - connecting: The replicator is connecting to the remote host.
+    ///   - idle: The replicator is inactive waiting for changes or offline.
+    ///   - busy: The replicator is actively transferring data.
     public enum ActivityLevel : UInt8 {
         case stopped = 0
         case offline
@@ -231,8 +232,9 @@ public final class Replicator {
     /// Check whether the document in the given collection is pending to push or not. If the given collection
     /// is not part of the replicator, an Invalid Parameter Exception will be thrown.
     ///
-    /// - Parameter collection The collection where the document belongs
-    /// - Parameter documentID: The ID of the document to check
+    /// - Parameters:
+    ///   - collection: The collection where the document belongs.
+    ///   - documentID: The ID of the document to check.
     /// - Returns: true if the document has one or more revisions pending, false otherwise
     public func isDocumentPending(_ documentID: String, collection: Collection) throws -> Bool {
         var error: NSError?

Swift/ReplicatorConfiguration.swift

@@ -21,10 +21,10 @@ import Foundation
 import CouchbaseLiteSwift_Private
 
 ///  Replicator type.
-///
-/// - pushAndPull: Bidirectional; both push and pull
-/// - push: Pushing changes to the target
-/// - pull: Pulling changes from the target
+/// - Note:
+///   - pushAndPull: Bidirectional; both push and pull
+///   - push: Pushing changes to the target
+///   - pull: Pulling changes from the target
 public enum ReplicatorType: UInt8 {
     case pushAndPull = 0
     case push
@@ -120,7 +120,7 @@ public struct ReplicatorConfiguration {
     /// Note: channels that are not accessible to the user will be ignored by
     /// Sync Gateway.
     ///
-    /// - Note:Channels are not supported in Peer-to-Peer and Database-to-Database replication.
+    /// - Note: Channels are not supported in Peer-to-Peer and Database-to-Database replication.
     @available(*, deprecated, message: """
                 Use init(target:) and config.addCollection(config:) with a CollectionConfiguration
                 object instead

Swift/Scope.swift

@@ -20,14 +20,14 @@
 import Foundation
 import CouchbaseLiteSwift_Private
 
-/// A CBLScope represents a scope or namespace of the collections.
+/// A Scope represents a scope or namespace of the collections.
 ///
 /// The scope implicitly exists when there is at least one collection created under the scope.
 /// The default scope is exceptional in that it will always exists even there are no collections
 /// under it.
 ///
-/// `CBLScope` Lifespan
-/// A `CBLScope` object remain valid until either the database is closed or
+/// `Scope` Lifespan
+/// A `Scope` object remain valid until either the database is closed or
 /// the scope itself is invalidated as all collections in the scope have been deleted. 
 public final class Scope {
 
@@ -50,6 +50,9 @@ public final class Scope {
     }
 
     /// Get a collection in the scope by name. If the collection doesn't exist, a nil value will be returned.
+    /// - Parameter name: Collection name as String.
+    /// - Returns: Collection object or nil if it doesn't exist.
+    /// - Throws: An error on when database object is not available.
     public func collection(name: String) throws -> Collection? {
         return try self.database.collection(name: name, scope: impl.name)
     }