WL#10008 (Document UUIDs) Documentation.

Author: rsomla1

include/devapi/collection_crud.h

@@ -201,15 +201,17 @@ namespace internal {
     Class which defines various variants of `add()` method.
 
     This class defines `add()` methods that append new documents to the
-    list of documents that should be inserted by a CollectionAdd operation.
+    list of documents that should be inserted by a `CollectionAdd` operation.
     Documents can be specified as JSON strings or DbDoc instances. Several
     documents can be added in a single call to `add()`.
 
+    @cond IGNORE
     Template is parametrized by return type of the `add()` method which
     is different in case of `CollectionAddBase` and `CollcetionAdd`.
     This return type is either `CollectionAdd` or reference to
     `CollectionAdd`, respectively. In either case `CollectionAdd::do_add()`
     method is used to append documents to the list.
+    @endcond
   */
 
   template<class AddOp>
@@ -341,10 +343,26 @@ namespace internal {
 /**
   Operation which adds documents to a collection.
 
+  Documents to be added by this operation are specified with various variants
+  of `add()` method.
+
+  Each document must have a unique identifier which is stored in `_id`
+  filed of the document. Document identifiers are character strings no longer
+  than 32 characters. If added document does not have `_id` field, a unique
+  identifier will be generated for it. Document identifier generated by given
+  collection add operation can be examined using `Result::getDocumentIds()`
+  method. Generated document identifiers are string of 32 hexadecimal digits,
+  like this one `0512020981044082E6119DFA0E4C0584`.
+
+  @note Generated document identifiers are based on UUIDs but they are not
+  valid UUIDs (fields are reversed).
+
+  @cond IGNORE
   The various `add()` methods defined by `CollectionAddInterface`
   call `do_add()` to append documents to the list one by one. This
   method, in turn, passes these documents to the internal
   implementation object.
+  @endcond
 
   @ingroup devapi_op
 */

include/mysql_devapi.h

@@ -960,7 +960,7 @@ class PUBLIC_API SessionSettings
     Possible connection options are:
 
     - `ssl-enable` : use TLS connection
-    - `ssl-ca=`<path> : path to a PEM file specifying trusted root certificates
+    - `ssl-ca=`path : path to a PEM file specifying trusted root certificates
 
     Specifying `ssl-ca` option implies `ssl-enable`.
   */
@@ -1254,8 +1254,16 @@ namespace internal {
 
     Schema getSchema(const string&, bool check_existence = false);
 
+    /**
+      Get the default schema specified when session was created.
+    */
+
     Schema getDefaultSchema();
 
+    /**
+      Get the name of the default schema specified when session was created.
+    */
+
     string getDefaultSchemaName();
 
     /**

include/mysql_xapi.h

@@ -437,7 +437,7 @@ mysqlx_get_session(const char *host, int port, const char *user,
   Possible connection options are:
 
   - `ssl-enable` : use TLS connection
-  - `ssl-ca=`<path> : path to a PEM file specifying trusted root certificates
+  - `ssl-ca=`path : path to a PEM file specifying trusted root certificates
 
   Specifying `ssl-ca` option implies `ssl-enable`.
 
@@ -1024,8 +1024,18 @@ mysqlx_collection_find(mysqlx_collection_t *collection, const char *criteria);
           NULL is returned only in case of an error. The error details
           can be obtained using `mysqlx_error()` function
 
-  @see `mysqlx_collection_add_new()` for additional information about
-  adding documents to a collection.
+  Each document must have a unique identifier which is stored in `_id`
+  filed of the document. Document identifiers are character strings no longer
+  than 32 characters. If added document does not have `_id` field, a unique
+  identifier will be generated for it. Document identifier generated by given
+  collection add operation can be examined using `mysqlx_fetch_doc_id()`
+  function. Generated document identifiers are strings of 32 hexadecimal digits,
+  like this one `0512020981044082E6119DFA0E4C0584`.
+
+  @note Generated document identifiers are based on UUIDs but they are not
+  valid UUIDs (fields are reversed).
+
+  @see `mysqlx_collection_add_new()`
 
   @ingroup xapi_coll
 */