DOC-8272-C4 --N1QL Tidy up https://issues.couchbase.com/browse/DOC-8272 (#523)

Author: ibsoln

modules/ROOT/pages/_partials/_attributes-local.adoc

@@ -297,7 +297,8 @@ endif::[]
 :snippets-pfx--android-kt: {snippets-pfx--android}kotlin/com/couchbase/code_snippets/
 :snippets-pfx--android-java: {snippets-pfx--android}java/com/couchbase/code_snippets/
 :snippets-pfx: example$code_snippets/
-:snippets-content--android-kotlin: {lang-mod-android}:{snippets-pfx--android-kt}Examples.kt
+// :snippets-content--android-kotlin: {lang-mod-android}:{snippets-pfx--android-kt}Examples.kt
+:snippets-content--android-kotlin: {lang-mod-android}:example$codesnippet_collection.kt
 :snippets-content--android-java: {lang-mod-android}:{snippets-pfx--android-java}Examples.java
 :snippets-content--c: {lang-mod-c}:{snippets-pfx}main.c
 :snippets-content--csharp: {lang-mod-csharp}:{snippets-pfx}Program.cs

modules/ROOT/pages/_partials/_block_tabbed_code_example.adoc

@@ -15,7 +15,7 @@
 //    include::partial$_block_show_snippet.adoc[]
 //    :param_tags!:
 //
-:self-tags:
+:self-tags: **
 ifdef::is-android[:is-tabbed:]
 ifdef::param-tags[:self-tags: {param-tags}]
 

modules/ROOT/pages/_partials/_page-index.adoc

@@ -178,7 +178,9 @@ ifndef::version[:version: version undefined]
 :release-notes--xref: {cbl--xref}{release-notes--page}[Release Notes]
 
 :replication--page:  replication.adoc
-:replication--xref: {cbl--xref}{replication--page}[Remote Sync Gateway]
+:replication--pfx: {cbl--xref}{replication--page}
+:replication--xref: {replication--pfx}[Remote Sync Gateway]
+:replication--xref--auto-purge: {replication--pfx}#anchor-auto-purge-on-revoke[Auto-purge on Channel Access Revocation]
 
 :save-blob--page:  save-blob.adoc
 :save-blob--xref: {cbl--xref}{save-blob--page}[Save Blob]

modules/ROOT/pages/_partials/cli-tool.adoc

@@ -1,5 +1,5 @@
 // Inclusion used in {src-lang}-database.adoc files
-`cblite` is a command-line tool for inspecting and querying Couchbase Lite 2.x databases.
+`cblite` is a command-line tool for inspecting and querying Couchbase Lite databases.
 
 You can download and build it from the couchbaselabs https://github.com/couchbaselabs/couchbase-mobile-tools/blob/master/README.cblite.md[GitHub repository].
 Note that the `cblite` tool is not supported by the https://www.couchbase.com/support-policy[Couchbase Support Policy].

modules/ROOT/pages/_partials/commons/common-blob.adoc

@@ -22,7 +22,6 @@ When a document is synchronized, the Couchbase Lite replicator adds an `_attachm
 
 == Blob Objects
 
-
 The blob as an object appears in a document as dictionary property -- see, for example _avatar_ in <<ex-blobobj>> and <<img-blob>>.
 
 Alternatively, you can save the blob to a database without associating it with any documents.
@@ -120,3 +119,4 @@ You could retrieved the blob using the Sync Gateway REST API at http://localhost
 image::ROOT:attach-replicated.png[]
 
 
+// include::{root-partials}block-related-content-data.adoc[]

modules/ROOT/pages/_partials/commons/common-database.adoc

@@ -1,6 +1,7 @@
 // BEGIN -- page-inclusion -- common-database.adoc
 // Applies to all platforms with some platform-specific differences
 
+
 include::{root-partials}_set-platform.adoc[]
 
 :param-related: {blob--xref} | {document--xref} | {indexing--xref}
@@ -30,27 +31,26 @@ endif::[]
 [#open-db]
 == Create or Open Database
 
-You can create a new database and-or open and existing database, using the {url-api-class-database} class.
+You can create a new database and-or open an existing database, using the {url-api-class-database} class.
 Just pass in a database name and optionally a {url-api-class-databasecfg} -- see <<ex-dbopen>>.
 
 Things to watch for include:
 
-* Opening/Creating a database is an asynchronous process
 * If the named database does not exist in the specified, or default, location then a new one is created
 * The database is created in a default location unless you  specify a directory for it -- see: {url-api-class-databasecfg} and {url-api-method-databasecfg-setdir}
 +
 --
 TIP: Best Practice is to always specify the path to the database explicitly.
 
 Typically, the default location for {param-title} is
-ifndef::is-csharp[]
-the application sandbox.
-endif::[]
+ifndef::is-csharp[the application sandbox]
+ifdef::is-c[or current working directory]
+.
 ifdef::is-csharp[]
 a platform-dependant location:
 
 include::{module-partials}database-finding-file.adoc[tags=list-only]
-endif::[]
+endif::is-csharp[]
 
 See also <<lbl-find-db-loc>>.
 --
@@ -60,41 +60,26 @@ See also <<lbl-find-db-loc>>.
 :param-tags: new-database
 include::{root-partials}_block_tabbed_code_example.adoc[]
 :param-tags!:
-<.> Here we are specifying the database directory path.
+// <.> Here we are specifying the database directory path.
 
 == Close Database
 
 You are advised to incorporate the closing of all open databases into your application workflow.
 
-Closing a database is a simple, just use {url-api-method-database-close} -- see: <<ex-dbclose>>. +
-However, there are a number of things to be aware of:
+Closing a database is a simple, just use {url-api-method-database-close} -- see: <<ex-dbclose>>.
+This also closes
+ifndef::is-c[{fn-2-8}]
+active replications, listeners and-or live queries connected to the database.
 
-* Closing a database is a *synchronous* operation, it is effective immediately
-* You cannot close a database that is not open. +
-Remember that opening (or creating) a database is asynchronous.
-So issuing a close immediately after initiating an open/create, may result in an error if that process has not completed.
+NOTE: Closing a database soon after starting a replication involving it can cause an exception as the asynchronous `replicator (start)` may not yet be `connected`.
 
-* Closing a database
-ifndef::is-c[{fn-2-8}]
- also closes any active replications, listeners and-or live queries attached to the database. +
-Closing a database immediately after kicking-off a replication could cause the sync to generate an exception. +
-For example: +
-`IllegalStateException: Attempt to perform an operation on a closed database`
 ifndef::is-c[]
 .Safely Closing a Database pre 2.8
-[TIP]
---
-. Stop any active live queries -- by removing the query's change listener
-. Remove any active replication change listeners
-. Stop any active replications -- this is an asynchronous operation
-. Wait for all active replications to fully stop -- for this you can monitor the replication status -- see: {xref-cbl-pg-replication--monitor-status}.
-. Finally, close the database
-
---
+TIP: Before closing, check that any attached listeners (query/replication/change) indicate they are at least at `connected` status before closing -- see for example: {xref-cbl-pg-replication--monitor-status}.
 endif::is-c[]
 
-[#ex-dbclose]
 .Close a Database
+[#ex-dbclose]
 :param-tags: close-database
 include::{root-partials}_block_tabbed_code_example.adoc[]
 :param-tags!:

modules/ROOT/pages/_partials/commons/common-indexing.adoc

@@ -37,11 +37,12 @@ include::{root-partials}_block-caveats.adoc[tag=index-partial-value]
 //end::overview[]
 
 
-.Creating a new index
-====
+== Creating a new index
 
-This example creates a new index for the `type` and `name` properties, shown in this data model:
+<<ex-create-index>> creates a new index for the `type` and `name` properties, shown in this data model:
 
+.Data Model
+====
 [source,json]
 ----
 {
@@ -50,6 +51,7 @@ This example creates a new index for the `type` and `name` properties, shown in
     "name": "Apple Droid"
 }
 ----
+====
 
 The code to create the index will look something like this:
 

modules/ROOT/pages/_partials/commons/common-querybuilder-n1ql.adoc

@@ -37,9 +37,10 @@ Then run the query using the`.execute()` method -- see {query-resultsets--xref}
 
 .Running a N1QL Query
 [#ex-samplerun]
-:param-tags: query-syntax-n1ql-params
+:param-tags: query-syntax-n1ql
 include::partial$_block_tabbed_code_example.adoc[]
 :param-tags!:
+<.> Here we are accessing th current database using the shorthand notation *`_`* -- see the <<lbl-from>> clause for more on data source selection and <<lbl-query-params>> for more on parameterized queries.
 
 
 == Query Format
@@ -147,8 +148,6 @@ This behavior is inline with that of Couchbase Server N1QL -- see example in <<t
 |===
 
 
-
-
 === Example
 
 .SELECT properties
@@ -299,7 +298,7 @@ where = WHERE expression <.>
 <.> WHERE evalates `expression` to a BOOLEAN value.
 You can chain any number of Expressions in order to implement sophisticated filtering capabilities.
 
-See also -- <<lbl-operators>> for more on building expressions
+See also -- <<lbl-operators>> for more on building expressions and <<lbl-query-params>> for more on parameterized queries.
 
 === Examples
 
@@ -2010,5 +2009,20 @@ TOSTRING
 |===
 endif::is-c[]
 
+[#lbl-query-params]
+== Query Parameters
+
+You can provide runtime parameters to yur N1QL query to make it more flexible.
+
+To specify substitutable parameters within your query string prefix the name with *`$`*, `$type` -- see: <<ex-sample-params>>.
+
+.Running a N1QL Query
+[#ex-sample-params]
+:param-tags: query-syntax-n1ql-params
+include::partial$_block_tabbed_code_example.adoc[]
+:param-tags!:
+
+<.> Define a parameter placeholder `$type`
+<.> Set the value of the `$type` parameter
 
 // END --- inclusion -- common-querybuilder-n1ql.adoc

modules/ROOT/pages/_partials/database-encryption.adoc

@@ -19,7 +19,7 @@ Couchbase Lite does not persist the key.
 It is the application's responsibility to manage the key and store it in a platform specific secure store such as Apple's https://developer.apple.com/documentation/security/keychain_services[Keychain] or Android's https://developer.android.com/training/articles/keystore[Keystore].
 
 An encrypted database can only be opened with the same language SDK that was used to encrypt it in the first place.
-So a database encrypted using the Swift SDK, and then exported, is readable only by the Swift SDK.
+So a database encrypted using the {param-title} SDK, and then exported, is readable only by the {param-title} SDK.
 
 ==== Upgrading from 1.x when Encryption is Enabled
 

modules/ROOT/pages/_partials/nav-skeleton.adoc

@@ -16,15 +16,18 @@ ifndef::is-c[** {querybuilder--xref}]
   ** {query-troubleshooting--xref}
 * {fts--xref}
 * {indexing--xref}
+ifndef::is-c[]
 * {landing-replications--xref}
-ifndef::is-c[  ** {dbreplica--xref}]
+  ** {dbreplica--xref}]
   ** {replication--xref}
-ifndef::is-c[]
   ** {p2psync-websocket--xref}
     *** {p2psync-websocket-using-passive--xref}
     *** {p2psync-websocket-using-active--xref}
     *** {p2psync-custom--xref}
 endif::is-c[]
+ifdef::is-c[]
+  * {replication--pfx}[Sync]
+endif::is-c[]
 * {conflict--xref}
 * {url-api-references}[API{nbsp}References]
 ifndef::is-c[* {dep-upgrade--xref}]