[docs] review and authentication docs (#2138)

* update supported version

* [docs] update paragraphs

* [docs] rel notes

* [docs] update paragraphs

* [docs] authentication docs

https://issues.couchbase.com/browse/DOC-3397

* EE/CE Objc

* EE/CE swift

* fix

* Update API doc references

* Update Carthage and Cocoapods instruction

* Update Carthage instructions

* Update cocoapods instruction for Swift

* [docs] mention about ordering during replication

* [docs] fix spacing, and code snippet per review.

* [docs] `.toDictionary()` method and document change events

* [docs] thread safety comment

https://issues.couchbase.com/browse/DOC-2954

Swift/Tests/SampleCodeTest.swift

@@ -91,6 +91,10 @@ class SampleCodeTest: CBLTestCase {
         newTask.setValue(Date(), forKey: "createdAt")
         let date = newTask.date(forKey: "createdAt")
         // # end::date-getter[]
+
+        // # tag::to-dictionary[]
+        newTask.toDictionary() // returns a Dictionary<String, Any>
+        // # end::to-dictionary[]
 
         print("\(date!)")
     }
@@ -113,6 +117,18 @@ class SampleCodeTest: CBLTestCase {
         }
         // # end::batch[]
     }
+
+    func dontTestChangeListener() throws {
+        database = self.db
+
+        // # tag::document-listener[]
+        database.addDocumentChangeListener(withID: "user.john") { (change) in
+            if let document = self.database.document(withID: change.documentID) {
+                print("Status :: \(document.string(forKey: "verified_account")!)")
+            }
+        }
+        // # end::document-listener[]
+    }
 
     func dontTestBlob() throws {
     #if TARGET_OS_IPHONE
@@ -498,6 +514,30 @@ class SampleCodeTest: CBLTestCase {
         // # end::replication-logging[]
     }
 
+    func dontTestReplicationBasicAuthentication() throws {
+        // # tag::basic-authentication[]
+        let url = URL(string: "ws://localhost:4984/mydatabase")!
+        let target = URLEndpoint(url: url)
+        let config = ReplicatorConfiguration(database: database, target: target)
+        config.authenticator = BasicAuthenticator(username: "john", password: "pass")
+
+        self.replicator = Replicator(config: config)
+        self.replicator.start()
+        // # end::basic-authentication[]
+    }
+
+    func dontTestReplicationSessionAuthentication() throws {
+        // # tag::session-authentication[]
+        let url = URL(string: "ws://localhost:4984/mydatabase")!
+        let target = URLEndpoint(url: url)
+        let config = ReplicatorConfiguration(database: database, target: target)
+        config.authenticator = SessionAuthenticator(sessionID: "904ac010862f37c8dd99015a33ab5a3565fd8447")
+
+        self.replicator = Replicator(config: config)
+        self.replicator.start()
+        // # end::session-authentication[]
+    }
+
     func dontTestReplicatorStatus() throws {
         // # tag::replication-status[]
         self.replicator.addChangeListener { (change) in

docs/modules/ROOT/pages/objc.adoc

@@ -32,7 +32,22 @@ navigator.
 ==== Carthage
 
 1.  https://github.com/Carthage/Carthage#installing-carthage[Install Carthage]
-2.  Add `github "couchbase/couchbase-lite-ios" "2.0DB023"` to your Cartfile.
+2.  In your *Cartfile*, add the following.
++
+*Couchbase Lite Community Edition*
++
+[source,ruby]
+----
+binary "https://raw.githubusercontent.com/couchbase/couchbase-lite-ios/master/Release/Carthage/CouchbaseLite-Community.json" ~> 2.0.0
+----
++
+*Couchbase Lite Enterprise Edition*
++
+[source,ruby]
+----
+binary "https://raw.githubusercontent.com/couchbase/couchbase-lite-ios/master/Release/Carthage/CouchbaseLite-Enterprise.json" ~> 2.0.0
+----
++
 3.  Run `carthage update --platform ios`.
 4.  Drag *CouchbaseLite.framework* from *Carthage/Build/* to the Xcode navigator.
 5.  Click on Project > General > Embedded Binary and add *CouchbaseLite.framework* to this section.
@@ -41,15 +56,28 @@ navigator.
 
 1.  https://guides.cocoapods.org/using/getting-started.html[Install
 Cocoapods]
-2.  In your `Podfile`, add the following.
+2.  In your *Podfile*, add the following.
++
+*Couchbase Lite Community Edition*
 +
 [source,ruby]
 ----
 target '<your target name>' do
   use_frameworks!
-  pod 'CouchbaseLite', :git => 'https://github.com/couchbase/couchbase-lite-ios.git', :tag => '2.0DB023', :submodules => true
+  pod 'CouchbaseLite', '~> 2.0.0'
 end
 ----
++
+*Couchbase Lite Enterprise Edition*
++
+[source,ruby]
+----
+target '<your target name>' do
+  use_frameworks!
+  pod 'CouchbaseLite-Enterprise', '~> 2.0.0'
+end
+----
++
 3.  Install the pods and open the .xcworkspace file generated by
 Cocoapods.
 +
@@ -91,6 +119,8 @@ Append the following inside of the `<dict>` XML tags to disable ATS.
 </dict>
 ----
 
+link:../installation/sync-gateway/index.html[Installing Sync Gateway ⟶]
+
 Supported Versions
 ~~~~~~~~~~~~~~~~~~
 
@@ -103,7 +133,7 @@ Supported Versions
 
 == API References
 
-http://docs.couchbase.com/mobile/2.0/couchbase-lite-objc/db022[Objective-C
+http://docs.couchbase.com/mobile/2.0/couchbase-lite-objc[Objective-C
 SDK API References]
 
 == Upgrading
@@ -141,7 +171,7 @@ Attachments that were persisted in the 1.x database will be copied to the 2.0 da
 include::{examplesdir}/SampleCodeTest.m[tags=1x-attachment]
 ----
 
-=== Replication
+=== Replication Compatibility
 
 The replication protocol used in Couchbase Lite 2.0 has been re-designed from the ground up and it is not backwards compatible with the 1.x replication protocol. Therefore, to use replication with Couchbase Lite 2.x, the target Sync Gateway instance must also be upgraded to 2.x.
 
@@ -365,23 +395,7 @@ With the SELECT statement, you can query and manipulate JSON data. With
 projections, you retrieve just the fields that you need and not the
 entire document.
 
-A SelectResult represents a single return value of the query statement.
-Documents in Couchbase Lite comprise of the document properties
-specified as a Dictionary of Key-Value pairs and associated metadata.
-The metadata consists of document Id and sequence Id associated with the
-Document. When you query for a document, the document metadata is not
-returned by default. You will need to explicitly query for the metadata.
-
-* http://docs.couchbase.com/mobile/2.0/couchbase-lite-objc/db022/Classes/CBLQuerySelectResult.html#/c:objc(cs)CBLQuerySelectResult(cm)all[`[CBLQuerySelectResult all]`]:
-Returns all properties associated with a document.
-* `[CBLQuerySelectResult expression:[`http://docs.couchbase.com/mobile/2.0/couchbase-lite-objc/db022/Classes/CBLQueryExpression.html[`CBLQueryExpression`]`property:"name"]`:
-Returns the `name` property associated with a document.
-* `[CBLQuerySelectResult expression:`http://docs.couchbase.com/mobile/2.0/couchbase-lite-objc/db022/Classes/CBLQueryMeta.html[`CBLQueryMeta`]`.id]`:
-Returns the document ID.
-* `SelectResult.expression(Expression.meta().sequence)`: Returns the
-sequence ID (used in replications).
-
-You can specify a comma separated list of `SelectResult` expressions in
+A SelectResult represents a single return value of the query statement. You can specify a comma separated list of `SelectResult` expressions in
 the select statement of your query. For instance the following select
 statement queries for the document `_id` as well as the `type` and
 `name` properties of all documents in the database. In the query result,
@@ -449,9 +463,7 @@ implement sophisticated filtering capabilities.
 
 ==== Comparison
 
-The `Expression`'s
-http://docs.couchbase.com/mobile/2.0/couchbase-lite-objc/db022/Classes/CBLQueryExpression.html[comparison
-operators] can be used in the WHERE statement to specify on which
+The http://docs.couchbase.com/mobile/2.0/couchbase-lite-objc/db022/Classes/CBLQueryExpression.html[comparison operators] can be used in the WHERE statement to specify on which
 property to match documents. In the example below, we use the `equalTo`
 operator to query documents where the `type` property equals "hotel".
 
@@ -867,6 +879,10 @@ speed and bandwidth utilization. The level of compression is set on Sync Gateway
 can be tuned in the configuration file
 (link:../guides/sync-gateway/config-properties/index.html#2.0/replicator_compression[`replicator_compression`]).
 
+==== Replication Ordering
+
+To optimize for speed, the replication protocol doesn't guarantee that documents will be received in a particular order. So we don't recommend to rely on that when using the replication or database change listeners for example.
+
 === Troubleshooting
 
 As always, when there is a problem with replication, logging is your
@@ -1011,3 +1027,39 @@ include::{examplesdir}/SampleCodeTest.m[tags=certificate-pinning]
 
 This example loads the certificate from the application sandbox, then
 converts it to the appropriate type to configure the replication object.
+
+== Release Notes
+
+*Bugs*
+
+* https://github.com/couchbase/couchbase-lite-ios/issues/1701[*#1701*]
+2:0 swift expression based query returning empty results
+* https://github.com/couchbase/couchbase-lite-ios/issues/1836[*#1836*]
+2.0: Database Listener callbacks not always getting called on main
+thread
+* https://github.com/couchbase/couchbase-lite-ios/issues/1854[*#1854*]
+2.0 : Dictionary, Array, and Fragment have duplicate definitions
+* https://github.com/couchbase/couchbase-lite-ios/issues/1862[*#1862*]
+2.0: CBLQueryExpression "and:" and "or:" methods cause syntax errors in
+Obj-C++
+* https://github.com/couchbase/couchbase-lite-ios/issues/2005[*#2005*]
+2.0: Make CBLDatabase query/replication tracking thread-safe
+* https://github.com/couchbase/couchbase-lite-ios/issues/2035[*#2035*]
+Cross Join Not Returning expected results
+* https://github.com/couchbase/couchbase-lite-ios/issues/2061[*#2061*]
+Swift 2.0: LiteCore error trying to copy prebuilt DB
+* https://github.com/couchbase/couchbase-lite-ios/issues/2085[*#2085*]
+Crashed in CBLWebSocket
+* https://github.com/couchbase/couchbase-lite-ios/issues/2094[*#2094*]
+TestSelfSignedSSLFailure_SG failed on iOS 10.2
+* https://github.com/couchbase/couchbase-lite-ios/issues/2104[*#2104*]
+Set Immutable Dictionary or Array to Document causes toDictionary() to
+crash in Swift
+
+*Known Issues*
+
+* https://github.com/couchbase/couchbase-lite-ios/issues/2112[*#2112*]
+HTTP proxy support
+* https://github.com/couchbase/couchbase-lite-ios/issues/2122[*#2122*]
+IOS 9 - Got LiteCore error: connection closed abnormally - eventual
+crash