Documentation update on row/document locking

Author: Bogdan Degtyariov

include/devapi/collection_crud.h

@@ -900,12 +900,24 @@ DIAGNOSTIC_POP
     return fields(rest...);
   }
 
+  /**
+    Set a shared mode lock on any rows/documents that are read.
+
+    Other sessions can read, but not modify locked rows/documents.
+  */
   CollectionGroupBy& lockShared()
   {
     get_impl()->set_locking(internal::Lock_mode::SHARED);
     return *this;
   }
 
+  /**
+    Set an exclusive mode lock on any rows/documents that are read.
+
+    Other sessions are blocked from modifying, locking, or reading the data
+    in certain transaction isolation levels. The lock is released
+    when the transaction is committed or rolled back.
+  */
   CollectionGroupBy& lockExclusive()
   {
     get_impl()->set_locking(internal::Lock_mode::EXCLUSIVE);

include/devapi/statement.h

@@ -191,12 +191,24 @@ class Statement
 
   Statement(Statement &&other) : Executable<Res,Op>(std::move(other)) {}
 
+  /**
+    Set a shared mode lock on any rows/documents that are read.
+
+    Other sessions can read, but not modify locked rows/documents.
+  */
   Executable<Res, Op> &lockShared()
   {
     get_impl()->set_locking(internal::Lock_mode::SHARED);
     return *this;
   }
 
+  /**
+    Set an exclusive mode lock on any rows/documents that are read.
+
+    Other sessions are blocked from modifying, locking, or reading the data
+    in certain transaction isolation levels. The lock is released
+    when the transaction is committed or rolled back.
+  */
   Executable<Res, Op> &lockExclusive()
   {
     get_impl()->set_locking(internal::Lock_mode::EXCLUSIVE);

include/mysql_xapi.h

@@ -444,9 +444,9 @@ typedef enum mysqlx_view_check_option_enum
 */
 typedef enum mysqlx_row_locking_enum
 {
-  LOCK_NONE = 0,
-  LOCK_SHARED = 1,
-  LOCK_EXCLUSIVE = 2
+  LOCK_NONE = 0,       /**< No locking */
+  LOCK_SHARED = 1,     /**< Locking in Shared mode */
+  LOCK_EXCLUSIVE = 2   /**< Locking in Exclusive mode */
 } mysqlx_row_locking_t;
 
 /*
@@ -2151,7 +2151,7 @@ PUBLIC_API int
 mysqlx_set_limit_and_offset(mysqlx_stmt_t *stmt, uint64_t row_count,
                             uint64_t offset);
 
-/*
+/**
   Set row locking mode for a statement.
 
   Set row locking mode for statement operations working on ranges of
@@ -2166,21 +2166,22 @@ mysqlx_set_limit_and_offset(mysqlx_stmt_t *stmt, uint64_t row_count,
   @param stmt statement handle
   @param locking the integer mode identifier (see `mysqlx_row_locking_t`).
          Possible values:
-           ROW_LOCK_NONE - no row locking is set
 
-           ROW_LOCK_SHARED - Sets a shared mode lock on any rows that
+           LOCK_NONE - Sets no row locking
+
+           LOCK_SHARED - Sets a shared mode lock on any rows that
               are read. Other sessions can read the rows,
               but cannot modify them until your transaction
               commits. If any of these rows were changed by
               another transaction that has not yet committed,
               your query waits until that transaction ends
               and then uses the latest values.
 
-           ROW_LOCK_EXCLUSIVE - For index records the search encounters,
+           LOCK_EXCLUSIVE - For index records the search encounters,
               locks the rows and any associated index entries, the same
               as if you issued an UPDATE statement for those rows. Other
               transactions are blocked from updating those rows,
-              from doing locking in ROW_LOCK_SHARED, or from reading
+              from doing locking in LOCK_SHARED, or from reading
               the data in certain transaction isolation levels.
 
   @return `RESULT_OK` - on success; `RESULT_ERR` - on error