docs: update api/database section

5 files changed, 46 insertions, 23 deletions

diff --git a/share/doc/src/api/database/common.rst b/share/doc/src/api/database/common.rst
index 853ff6bb7..a131e39b1 100644
--- a/share/doc/src/api/database/common.rst
+++ b/share/doc/src/api/database/common.rst
@@ -19,7 +19,7 @@
 
   Returns the HTTP Headers containing a minimal amount of information
   about the specified database. Since the response body is empty this method
-  is a lightweight way to check is database exists or not.
+  is a lightweight way to check if the database exists already or not.
 
   :param db: Database name
   :code 200: Database exists
@@ -158,8 +158,8 @@
         "ok": true
     }
 
-  If we repeat same request to CouchDB, it will response with :code:`412` since
-  database is already exists:
+  If we repeat the same request to CouchDB, it will response with :code:`412`
+  since the database already exists:
 
   **Request**:
 
@@ -185,7 +185,7 @@
         "reason": "The database could not be created, the file already exists."
     }
 
-  In case of invalid database name CouchDB returns response with :code:`400`:
+  If an invalid database name is supplied, CouchDB returns response with :code:`400`:
 
   **Request**:
 
@@ -225,8 +225,8 @@
   :>json boolean ok: Operation status
   :code 200: Database removed successfully
   :code 400: Invalid database name
-  :code 404: Database doesn't already exists
   :code 401: CouchDB Server Administrator privileges required
+  :code 404: Database doesn't exist
 
   **Request**:
 
@@ -260,7 +260,8 @@
   If the JSON structure includes the ``_id`` field, then the document will be
   created with the specified document ID.
 
-  If the ``_id`` field is not specified, a new unique ID will be generated.
+  If the ``_id`` field is not specified, a new unique ID will be generated,
+  following whatever UUID algorithm is configured for that server.
 
   :param db: Database name
   :<header Accept: - :mimetype:`application/json`
@@ -282,8 +283,8 @@
   :code 202: Document data accepted, but not yet stored on disk
   :code 400: Invalid database name
   :code 401: Write privileges required
-  :code 404: Database doesn't already exists
-  :code 409: Document with the specified document ID already exists
+  :code 404: Database doesn't exist
+  :code 409: A Conflicting Document with same ID already exists
 
   **Request**:
 
@@ -380,10 +381,11 @@ respond with a HTTP :http:statuscode:`202` response code immediately.
 
 .. note::
 
-   Creating or updating documents with batch mode doesn't guarantees that
-   document will be successfully stored on disk and CouchDB doesn't ensures you
-   that it will to. Document may not be saved due to conflicts, rejection by
-   :ref:`validation function <vdufun>` or by other reasons.
+   Creating or updating documents with batch mode doesn't guarantee that
+   document will be successfully stored on disk and CouchDB does not
+   guarantee that. For example, individual documents may not be saved due to
+   conflicts, rejection by :ref:`validation function <vdufun>` or by other
+   reasons, even if overall the batch transfer was sucessfully submitted.
 
 **Request**:
 
diff --git a/share/doc/src/api/database/compact.rst b/share/doc/src/api/database/compact.rst
index 6982cb423..81935db2a 100644
--- a/share/doc/src/api/database/compact.rst
+++ b/share/doc/src/api/database/compact.rst
@@ -21,9 +21,9 @@
   Request compaction of the specified database. Compaction compresses the
   disk database file by performing the following operations:
 
-  -  Writes a new version of the database file, removing any unused
+  -  Writes a new, optimised, version of the database file, removing any unused
      sections from the new version during write. Because a new file is
-     temporary created for this purpose, you will need twice the current
+     temporarily created for this purpose, you may require up to twice the current
      storage space of the specified database in order for the compaction
      routine to complete.
 
@@ -130,6 +130,11 @@
         "ok": true
     }
 
+    .. note::
+
+      View indexes are stored in a separate ``.couch`` file based on
+      a hash of the design document's relevant functions, in a sub directory
+      of where the main ``.couch`` database files are located.
 
 .. _api/db/ensure_full_commit:
 
@@ -187,7 +192,10 @@
 
 .. http:post:: /{db}/_view_cleanup
 
-  Cleans up the cached view output on disk for a given view.
+  Removes view index files that are no longer required by CouchDB as a result
+  of changed views within design documents. As the view filename is based on
+  a hash of the view functions, over time old views will remain, consuming
+  storage. This call cleans up the cached view output on disk for a given view.
 
   :param db: Database name
   :<header Accept: - :mimetype:`application/json`
diff --git a/share/doc/src/api/database/misc.rst b/share/doc/src/api/database/misc.rst
index d3507a541..ad46e1522 100644
--- a/share/doc/src/api/database/misc.rst
+++ b/share/doc/src/api/database/misc.rst
@@ -19,12 +19,20 @@
 .. http:post:: /{db}/_purge
 
   A database purge permanently removes the references to deleted documents
-  from the database. Deleting a document within CouchDB does not actually
+  from the database. Normal deletion of a document within CouchDB does not
   remove the document from the database, instead, the document is marked as
-  a deleted (and a new revision is created). This is to ensure that
-  deleted documents are replicated to other databases as having been
+  ``_deleted=true`` (and a new revision is created). This is to ensure that
+  deleted documents can be replicated to other databases as having been
   deleted. This also means that you can check the status of a document and
-  identify that the document has been deleted.
+  identify that the document has been deleted by its absence.
+
+  .. warning::
+
+     Purging a document from a database should only be done as a last resort
+     when sensitive information has been introduced inadvertently into a
+     database. In clustered or replicated environments it is very difficult
+     to guarantee that a particular purged document has been removed from all
+     replicas. Do not rely on this API as a way of doing secure deletion.
 
   The purge operation removes the references to the deleted documents from
   the database. The purging of old documents is not replicated to other
diff --git a/share/doc/src/api/database/security.rst b/share/doc/src/api/database/security.rst
index 8ad62e658..ee95ee4cc 100644
--- a/share/doc/src/api/database/security.rst
+++ b/share/doc/src/api/database/security.rst
@@ -31,7 +31,7 @@
     write (and edit) design documents, add/remove database admins and members,
     set the :ref:`database revisions limit <api/db/revs_limit>` and execute
     :ref:`temporary views <api/db/temp_view>` against the database.
-    They can not create a database and neither delete a database.
+    They can not create a database nor delete a database.
 
   Both ``members`` and ``admins`` objects are contains two array-typed fields:
 
@@ -56,6 +56,7 @@
   read documents from the database (or do a :http:get:`/{db}` call).
 
   .. note::
+
      If the security object for a database has never been set, then the
      value returned will be empty.
 
diff --git a/share/doc/src/api/database/temp-views.rst b/share/doc/src/api/database/temp-views.rst
index 0b576b817..d9ac16df0 100644
--- a/share/doc/src/api/database/temp-views.rst
+++ b/share/doc/src/api/database/temp-views.rst
@@ -23,9 +23,13 @@
 
   The arguments also available to standard view requests also apply to
   temporary views, but the execution of the view may take some time as it
-  relies on being executed at the time of the request. In addition to the
-  time taken, they are also computationally very expensive to produce. You
-  should use a defined view if you want to achieve the best performance.
+  relies on being executed at the time of the request. This means that for
+  every temporary view you create, the entire database will be read
+  one doc at a time and passed through the view function.
+
+  This should not be used on production CouchDB instances, and is purely a
+  convenience function for quick development testing. You should use a
+  defined view if you want to achieve the best performance.
 
   See :ref:`api/ddoc/view` for more info.