docs: 8.0.6 updates - part 2

Author: rsomla1

cdk/parser/uri_parser.cc

@@ -277,7 +277,7 @@ struct URI_parser::Guard
 
 
 /*
-  Character classess defined by the grammar.
+  Character classes defined by the grammar.
 */
 
 #define LIST(X,Y)  T_##X,

doc/devapi_ref.txt

@@ -91,7 +91,8 @@ a result (ignored here; the results are used later).
 To insert documents use the @link mysqlx::Collection::add
 `Collection::add()`@endlink method. Documents are described by JSON strings
 using the same syntax as MySQL Server. Note that double quotes are required
-around field names and they must be escaped inside C strings:
+around field names and they must be escaped inside C strings, unless the new
+C++11 `R"(...)"` string literal syntax is used as in the example below:
 
 @skipline {
 @until cout

include/devapi/collection_crud.h

@@ -29,9 +29,9 @@
   @file
   Declarations for CRUD operations on document collections.
 
-  Classes declared here represent CRUD operations on a given document
+  Classes declared here represent CRUD operations on a document
   collection. An Object of a class such as CollectionAdd represents
-  a "yet-to-be-executed" operation and stores all the parameters for the
+  a "yet-to-be-executed" operation and stores all the parameters of the
   operation. The operation is sent to server for execution only when
   `execute()` method is called.
 
@@ -51,9 +51,11 @@
   CRUD operation objects have methods which can modify the operation
   before it gets executed. For example `CollectionAdd::add()`
   appends a document to the list of documents that should be added
-  by given CollectionAdd operation. These methods can be chained
+  by the given CollectionAdd operation. These methods can be chained
   as allowed by the fluent API grammar.
 
+  @internal
+
   The order of fluent API calls is expressed by base classes, such as
   Collection_find_base, which are composed from CRUD templates defined
   in crud.h. The order of templates determines the allowed order of fluent
@@ -104,17 +106,17 @@ struct Collection_add_base
 
 
 /**
-  Operation which adds documents to a collection.
+  An 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`
   field of the document. Document identifiers are character strings no longer
   than 32 characters. If added document does not have `_id` field, a unique
-  identifier is generated for it. Document identifier generated by given
+  identifier is generated for it. Document identifier generated by a given
   collection add operation can be examined using `Result::getDocumentIds()`
-  method. Generated document identifiers are string of 32 hexadecimal digits,
+  method. 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
@@ -140,7 +142,7 @@ DLL_WARNINGS_POP
 public:
 
   /**
-    Create empty add operation for a given collection.
+    Create an empty add operation for the given collection.
   */
 
   CollectionAdd(Collection &coll);
@@ -157,9 +159,7 @@ DLL_WARNINGS_POP
 
 
   /**
-    Add all documents from a range defined by two iterators. These
-    iterators should return a document object of one of accepted types
-    (as given by the is_doc_type<> trait).
+    Add all documents from a range defined by two iterators.
   */
 
   template <typename It>
@@ -241,7 +241,7 @@ struct Collection_remove_base
 
 
 /**
-  Class representing operation which removes documents from a collection.
+  An operation which removes documents from a collection.
 
   @ingroup devapi_op
 
@@ -257,17 +257,19 @@ class PUBLIC_API CollectionRemove
 public:
 
   /**
-    Create empty remove operation for a given collection.
+    Create an empty remove operation for the given collection.
   */
 
   CollectionRemove(Collection &coll);
 
   /**
-    Create remove operation for given collection and documents
-    selected by an expression.
+    Create an operation which removes selected documnets from the given
+    collection.
+
+    Documents to be removed are specified by the given Boolean expression.
   */
 
-  CollectionRemove(Collection &coll, const string&);
+  CollectionRemove(Collection &coll, const string &expr);
 
 
   CollectionRemove(const internal::Collection_remove_cmd &other)
@@ -308,7 +310,7 @@ struct Collection_find_base
 
 
 /**
-  Operation which returns all or selected documents from a collection.
+  An operation which returns all or selected documents from a collection.
 
   @ingroup devapi_op
 */
@@ -327,17 +329,19 @@ DLL_WARNINGS_POP
 public:
 
   /**
-    Create operation which returns all documents from a collection.
+    Create an operation which returns all documents from the given collection.
   */
 
   CollectionFind(Collection &coll);
 
   /**
-    Create operation which returns all documents from a collection
-    which satisfy given criteria.
+    Create an operation which returns selected documents from the given
+    collection.
+
+    Documents to be returned are specified by the given Boolean expression.
   */
 
-  CollectionFind(Collection &coll, const string&);
+  CollectionFind(Collection &coll, const string &expr);
 
 
   CollectionFind(const internal::Collection_find_cmd &other)
@@ -354,7 +358,7 @@ DLL_WARNINGS_POP
 public:
 
   /**
-    Specify projection for the documents found by this query.
+    Specify a projection for the documents returned by this operation.
 
     Projection is either a single document expression given by `expr(<string>)`
     or a list (or collection) of strings of the form
@@ -415,7 +419,7 @@ struct Collection_replace_base
 {};
 
 /*
-  Operation which replaces a document, using the id by a new one
+  An operation which replaces a single document with a new one.
 */
 
 class PUBLIC_API CollectionReplace
@@ -456,7 +460,7 @@ class PUBLIC_API CollectionReplace
 
 
 /**
-  Operation which modifies all or selected documents in a collection.
+  An operation which modifies all or selected documents in a collection.
 
   @ingroup devapi_op
 */
@@ -467,7 +471,12 @@ class PUBLIC_API CollectionModify
 
 public:
 
-  /// Create operation which modifies selected documents in a collection.
+  /**
+    Create an operation which modifies selected documents in the given
+    collection.
+
+    Documents to be modified are specified by the given Boolean expression.
+  */
 
   CollectionModify(Collection &base, const string &expr);
 
@@ -484,10 +493,11 @@ class PUBLIC_API CollectionModify
 
 
   /**
-    Set a given field in a document to the given value.
+    Set the given field in a document to the given value.
 
-    Field is given by a document path. The value can be either a direct literal
-    or an expression given by `expr(<string>)`, evaluated on the server.
+    The field is given by a document path. The value can be either a direct
+    literal or an expression given as `expr(<string>)`, to be evaluated on
+    the server.
   */
 
   CollectionModify& set(const Field &field, internal::ExprValue &&val)
@@ -500,7 +510,7 @@ class PUBLIC_API CollectionModify
   }
 
   /**
-    Unset a given field in a document.
+    Remove the given field from a document.
 
     The field is given by a document path.
   */
@@ -515,7 +525,7 @@ class PUBLIC_API CollectionModify
   }
 
   /**
-    Insert value into an array field of a document.
+    Insert a value into an array field of a document.
 
     The `field` parameter should be a document path pointing at a location
     inside an array field. The given value is inserted at this position.
@@ -531,7 +541,7 @@ class PUBLIC_API CollectionModify
   }
 
   /**
-    Append value to an array field of a document.
+    Append a value to an array field of a document.
 
     The `field` parameter should be a document path pointing at an array
     field inside the document. The given value is appended at the end of the
@@ -548,10 +558,10 @@ class PUBLIC_API CollectionModify
   }
 
   /**
-    Delete element from an array field of a document.
+    Delete an element from an array field of a document.
 
     The `field` parameter should be a document path pointing at a location
-    inside an array field. The element at indicated location is removed from
+    inside an array field. The element at the indicated location is removed from
     the array.
   */
 

include/devapi/common.h

@@ -167,15 +167,15 @@ typedef unsigned long row_count_t;
   Method `begin()` returns pointer to the first byte in the
   region, `end()` to one past the last byte in the region.
 
-  @note Instance of `bytes` type does not store the bytes -
+  @note An instance of `bytes` does not store the bytes -
   it merely describes a region of memory and is equivalent
   to a pair of pointers. It is very cheap to copy `bytes` and
   pass them by value.
 
   @note This class extends std::pair<byte *, size_t> to make
   it consistent with how memory regions are described by
   std::get_temporary_buffer(). It is also possible to initialize
-  bytes instance by buffer returned from
+  a `bytes` instance by buffer returned from
   std::get_temporary_buffer(), as follows:
 
     bytes buf = std::get_temporary_buffer<byte>(size);