libcouchbase 1.3.0 → 1.3.2

data/ext/libcouchbase/include/libcouchbase/deprecated.h

@@ -294,6 +294,18 @@ typedef enum {
     LCB_HTTP_STATUS_INSUFFICIENT_STORAGE = 507
 } lcb_http_status_t;
 
+/**
+ * @deprecated
+ */
+typedef enum {
+    /* encryption (e.g. private key for assymetric ciphers) */
+    LCBCRYPTO_KEY_ENCRYPT = 0,
+    /* decryption (e.g. private key for assymetric ciphers) */
+    LCBCRYPTO_KEY_DECRYPT = 1,
+    LCBCRYPTO_KEY__MAX
+} lcbcrypto_KEYTYPE;
+
+
 #ifdef __cplusplus
 }
 #endif

data/ext/libcouchbase/include/libcouchbase/error.h

@@ -460,87 +460,118 @@ typedef enum {
     X(LCB_MUTATION_LOST, 0x3E, LCB_ERRTYPE_SRVGEN,\
       "The given mutation has been permanently lost due to the node failing " \
       "before replication") \
+    /** Sub-document path does not exist */ \
     X(LCB_SUBDOC_PATH_ENOENT, 0x3F, \
       LCB_ERRTYPE_DATAOP|LCB_ERRTYPE_SRVGEN|LCB_ERRTYPE_SUBDOC, \
       "Sub-document path does not exist") \
+    /** Type of element in sub-document path conflicts with type in document */ \
     X(LCB_SUBDOC_PATH_MISMATCH, 0x40,\
       LCB_ERRTYPE_DATAOP|LCB_ERRTYPE_SRVGEN|LCB_ERRTYPE_SUBDOC, \
       "Type of element in sub-document path conflicts with type in document") \
+    /** Malformed sub-document path */ \
     X(LCB_SUBDOC_PATH_EINVAL, 0x41, \
       LCB_ERRTYPE_INPUT|LCB_ERRTYPE_SRVGEN|LCB_ERRTYPE_SUBDOC, \
       "Malformed sub-document path") \
+    /** Sub-document contains too many components */ \
     X(LCB_SUBDOC_PATH_E2BIG, 0x42, \
       LCB_ERRTYPE_INPUT|LCB_ERRTYPE_SRVGEN|LCB_ERRTYPE_SUBDOC, \
       "Sub-document contains too many components") \
+    /** Existing document contains too many levels of nesting */ \
     X(LCB_SUBDOC_DOC_E2DEEP, 0x43,\
       LCB_ERRTYPE_DATAOP|LCB_ERRTYPE_SRVGEN|LCB_ERRTYPE_SUBDOC, \
       "Existing document contains too many levels of nesting") \
+    /** Subdocument operation would invalidate the JSON */ \
     X(LCB_SUBDOC_VALUE_CANTINSERT, 0x44, \
       LCB_ERRTYPE_INPUT|LCB_ERRTYPE_SRVGEN|LCB_ERRTYPE_SUBDOC, \
       "Subdocument operation would invalidate the JSON") \
+    /** Existing document is not valid JSON */ \
     X(LCB_SUBDOC_DOC_NOTJSON, 0x45,\
       LCB_ERRTYPE_DATAOP|LCB_ERRTYPE_SRVGEN|LCB_ERRTYPE_SUBDOC, \
       "Existing document is not valid JSON") \
+    /** The existing numeric value is too large */ \
     X(LCB_SUBDOC_NUM_ERANGE, 0x46, \
       LCB_ERRTYPE_DATAOP|LCB_ERRTYPE_SRVGEN|LCB_ERRTYPE_SUBDOC, \
       "The existing numeric value is too large") \
+    /** Delta must be numeric, within the 64 bit signed range, and non-zero */ \
     X(LCB_SUBDOC_BAD_DELTA, 0x47,\
       LCB_ERRTYPE_DATAOP|LCB_ERRTYPE_SRVGEN|LCB_ERRTYPE_SUBDOC, \
       "Delta must be numeric, within the 64 bit signed range, and non-zero") \
+    /** The given path already exists in the document */ \
     X(LCB_SUBDOC_PATH_EEXISTS, 0x48,\
       LCB_ERRTYPE_DATAOP|LCB_ERRTYPE_SRVGEN|LCB_ERRTYPE_SUBDOC, \
       "The given path already exists in the document") \
+    /** Could not execute one or more multi lookups or mutations */ \
     X(LCB_SUBDOC_MULTI_FAILURE, 0x49,\
       LCB_ERRTYPE_DATAOP|LCB_ERRTYPE_SRVGEN|LCB_ERRTYPE_SUBDOC, \
       "Could not execute one or more multi lookups or mutations") \
+    /** Value is too deep to insert */ \
     X(LCB_SUBDOC_VALUE_E2DEEP, 0x4A,\
       LCB_ERRTYPE_INPUT|LCB_ERRTYPE_SRVGEN|LCB_ERRTYPE_SUBDOC, \
       "Value is too deep to insert") \
+    /** A badly formatted packet was sent to the server. Please report this in a bug */ \
     X(LCB_EINVAL_MCD, 0x4B, LCB_ERRTYPE_SRVGEN|LCB_ERRTYPE_INTERNAL, \
         "A badly formatted packet was sent to the server. Please report this in a bug") \
+    /** Missing subdocument path */ \
     X(LCB_EMPTY_PATH, 0x4C, LCB_ERRTYPE_INPUT, "Missing subdocument path") \
+    /** Unknown subdocument command */ \
     X(LCB_UNKNOWN_SDCMD, 0x4D, LCB_ERRTYPE_INPUT, "Unknown subdocument command") \
+    /** No commands specified */ \
     X(LCB_ENO_COMMANDS, 0x4E, LCB_ERRTYPE_INPUT, "No commands specified") \
+    /** Query execution failed. Inspect raw response object for information */ \
     X(LCB_QUERY_ERROR, 0x4F, LCB_ERRTYPE_SRVGEN, \
         "Query execution failed. Inspect raw response object for information") \
-    \
+    /** Generic temporary error received from server*/ \
     X(LCB_GENERIC_TMPERR, 0x50, LCB_ERRTYPE_TRANSIENT|LCB_ERRTYPE_SRVGEN, \
         "Generic temporary error received from server") \
+    /** Generic subdocument error received from server*/ \
     X(LCB_GENERIC_SUBDOCERR, 0x51, LCB_ERRTYPE_SUBDOC|LCB_ERRTYPE_SRVGEN, \
         "Generic subdocument error received from server") \
+    /** Generic constraint error received from server*/ \
     X(LCB_GENERIC_CONSTRAINT_ERR, 0x52, LCB_ERRTYPE_INPUT|LCB_ERRTYPE_SRVGEN, \
         "Generic constraint error received from server") \
+    /** Invalid reply received from nameserver*/ \
     X(LCB_NAMESERVER_ERROR, 0x53, LCB_ERRTYPE_NETWORK, \
         "Invalid reply received from nameserver") \
+    /** Not authorized for operation*/ \
     X(LCB_NOT_AUTHORIZED, 0x54, LCB_ERRTYPE_INPUT|LCB_ERRTYPE_SRVGEN, \
         "Not authorized for operation") \
+    /** An invalid combination of commands was specified*/ \
     X(LCB_SUBDOC_INVALID_COMBO, 0x55, \
       LCB_ERRTYPE_INPUT|LCB_ERRTYPE_SRVGEN|LCB_ERRTYPE_SUBDOC,  \
       "An invalid combination of commands was specified") \
+    /** Specified key was successfully found, but one or more path operations failed*/ \
     X(LCB_SUBDOC_MULTI_PATH_FAILURE, 0x56, \
       LCB_ERRTYPE_INPUT|LCB_ERRTYPE_SRVGEN|LCB_ERRTYPE_SUBDOC, \
       "Specified key was successfully found, but one or more path operations failed") \
+    /** The operation completed successfully, but operated on a deleted document*/ \
     X(LCB_SUBDOC_SUCCESS_DELETED, 0x57, \
       LCB_ERRTYPE_INPUT|LCB_ERRTYPE_SRVGEN|LCB_ERRTYPE_SUBDOC, \
       "The operation completed successfully, but operated on a deleted document") \
+    /** The combination of the subdoc flags for the xattrs is not valid*/ \
     X(LCB_SUBDOC_XATTR_INVALID_FLAG_COMBO, 0x58, \
       LCB_ERRTYPE_INPUT|LCB_ERRTYPE_SRVGEN|LCB_ERRTYPE_SUBDOC, \
       "The combination of the subdoc flags for the xattrs is not valid") \
+    /** Only a single xattr key may be accessed at the same time*/ \
     X(LCB_SUBDOC_XATTR_INVALID_KEY_COMBO, 0x59, \
       LCB_ERRTYPE_INPUT|LCB_ERRTYPE_SRVGEN|LCB_ERRTYPE_SUBDOC, \
       "Only a single xattr key may be accessed at the same time") \
+    /** The server has no knowledge of the requested macro*/ \
     X(LCB_SUBDOC_XATTR_UNKNOWN_MACRO, 0x5a, \
       LCB_ERRTYPE_INPUT|LCB_ERRTYPE_SRVGEN|LCB_ERRTYPE_SUBDOC, \
       "The server has no knowledge of the requested macro") \
+    /** The server has no knowledge of the requested virtual xattr */ \
     X(LCB_SUBDOC_XATTR_UNKNOWN_VATTR, 0x5b, \
       LCB_ERRTYPE_INPUT|LCB_ERRTYPE_SRVGEN|LCB_ERRTYPE_SUBDOC, \
       "The server has no knowledge of the requested virtual xattr") \
+    /** Virtual xattrs cannot be modified */ \
     X(LCB_SUBDOC_XATTR_CANT_MODIFY_VATTR, 0x5c, \
       LCB_ERRTYPE_INPUT|LCB_ERRTYPE_SRVGEN|LCB_ERRTYPE_SUBDOC, \
       "Virtual xattrs cannot be modified") \
+    /** Specified key was found as a deleted document, but one or more path operations failed*/ \
     X(LCB_SUBDOC_MULTI_PATH_FAILURE_DELETED, 0x5d, \
       LCB_ERRTYPE_INPUT|LCB_ERRTYPE_SRVGEN|LCB_ERRTYPE_SUBDOC, \
       "Specified key was found as a deleted document, but one or more path operations failed") \
+    /** According to the spec all xattr commands should come first, followed by the commands for the document body */ \
     X(LCB_SUBDOC_INVALID_XATTR_ORDER, 0x5e,                    \
       LCB_ERRTYPE_INPUT|LCB_ERRTYPE_SRVGEN|LCB_ERRTYPE_SUBDOC, \
       "According to the spec all xattr commands should come first, followed by the commands for the document body")
@@ -558,7 +589,7 @@ typedef enum {
     LCB_MAX_ERROR_VAL,
     #endif
 
-    /* The errors below this value reserver for libcouchbase usage. */
+    /** The errors below this value reserved for libcouchbase usage. */
     LCB_MAX_ERROR = 0x1000
 } lcb_error_t;
 

data/ext/libcouchbase/include/libcouchbase/ixmgmt.h

@@ -43,7 +43,7 @@ typedef struct {
      * populate the internal equivalents of the fields in this structure.
      *
      * Note that when using this field as an input for creating indexes, you
-     * should still set the ::flags field if you wish to set flags (e.g. in
+     * should still set the @ref flags field if you wish to set flags (e.g. in
      * order to create a deferred-build index).
      */
     const char *rawjson;

data/ext/libcouchbase/include/libcouchbase/n1ql.h

@@ -25,8 +25,48 @@ extern "C" {
 
 /**
  * @ingroup lcb-public-api
- * @defgroup lcb-n1ql-api N1QL
- * @brief Execute N1QL queries and receive resultant rows
+ * @defgroup lcb-n1ql-api N1QL/Analytics
+ * @brief Execute N1QL/Analytics queries.
+ *
+ * Query language based on SQL, but designed for structured and flexible JSON
+ * documents. Querying can solve typical programming tasks such as finding a
+ * user profile by email address, performing aggregations etc.
+ *
+ * @code{.c}
+ * const char *query = "{\"statement\":\"SELECT * FROM breweries LIMIT 10\"}";
+ * lcb_CMDN1QL cmd = {0};
+ * int idx = 0;
+ * // NOTE: with this flag, the request will be issued to Analytics service
+ * cmd.cmdflags = LCB_CMDN1QL_F_ANALYTICSQUERY;
+ * cmd.callback = row_callback;
+ * cmd.query = query;
+ * cmd.nquery = strlen(query);
+ * lcb_n1ql_query(instance, &idx, &cmd);
+ * lcb_wait(instance);
+ * @endcode
+ *
+ * Where row_callback might be implemented like this:
+ *
+ * @code{.c}
+ * static void row_callback(lcb_t instance, int type, const lcb_RESPN1QL *resp)
+ * {
+ *     int *idx = (int *)resp->cookie;
+ *     if (resp->rc != LCB_SUCCESS) {
+ *         printf("failed to execute query: %s\n", lcb_strerror_short(resp->rc));
+ *         exit(EXIT_FAILURE);
+ *     }
+ *     if (resp->rflags & LCB_RESP_F_FINAL) {
+ *         printf("META: ");
+ *     } else {
+ *         printf("ROW #%d: ", (*idx)++);
+ *     }
+ *     printf("%.*s\n", (int)resp->nrow, (char *)resp->row);
+ * }
+ * @endcode
+ *
+ * @see more details on @ref lcb_n1ql_query and @ref lcb_CMDN1QL.
+ *
+ * Also there is a query builder available for N1QL queries: @ref lcb_n1p_new/@ref lcb_n1p_mkcmd.
  */
 
 /**
@@ -35,6 +75,9 @@ extern "C" {
  */
 typedef struct lcb_RESPN1QL lcb_RESPN1QL;
 typedef struct lcb_CMDN1QL lcb_CMDN1QL;
+/**
+ * Pointer for request instance
+ */
 typedef struct lcb_N1QLREQ* lcb_N1QLHANDLE;
 
 /**
@@ -324,13 +367,13 @@ lcb_n1p_mkcmd(lcb_N1QLPARAMS *params, lcb_CMDN1QL *cmd);
 #define LCB_CMDN1QL_F_JSONQUERY (1 << 17)
 
 /**
- * This is an analytics query. Use the `host` field to specify the host/port
- * to target. When this flag is set, things like prepared queries and
- * parametrized statements will not work.
+ * This is an Analytics query.
  *
- * @uncommitted
+ * @committed
  */
-#define LCB_CMDN1QL_F_CBASQUERY (1 << 18)
+#define LCB_CMDN1QL_F_ANALYTICSQUERY (1 << 18)
+/* @private an alias for compatibility */
+#define LCB_CMDN1QL_F_CBASQUERY LCB_CMDN1QL_F_ANALYTICSQUERY
 
 /**
  * Command structure for N1QL queries. Typically an application will use the
@@ -406,6 +449,8 @@ struct lcb_RESPN1QL {
  *
  * This function will send the query to a query server in the cluster
  * and will invoke the callback (lcb_CMDN1QL::callback) for each result returned.
+ * By default it will run query as N1QL flavour, for Analytics set
+ * @ref LCB_CMDN1QL_F_ANALYTICSQUERY flag in cmdflags of @ref lcb_CMDN1QL argument.
  *
  * @param instance The instance
  * @param cookie Pointer to application data
@@ -447,18 +492,47 @@ LIBCOUCHBASE_API
 void
 lcb_n1ql_cancel(lcb_t instance, lcb_N1QLHANDLE handle);
 
+/**@}*/
+
+/**@}*/
+
+/**
+ * @ingroup lcb-public-api
+ * @addtogroup lcb-tracing-api
+ * @{
+ */
 #ifdef LCB_TRACING
+
 /**
- * @uncommitted
+ * Associate parent tracing span with the N1QL request.
+ *
+ * @param instance the instance
+ * @param handle N1QL request handle
+ * @param span parent span
+ *
+ * @par Attach parent tracing span to request object.
+ * @code{.c}
+ * lcb_CMDN1QL cmd = {};
+ * // initialize N1QL command...
+ *
+ * lcb_N1QLHANDLE handle = NULL;
+ * cmd->handle = &handle;
+ *
+ * lcb_error_t err = lcb_fts_query(instance, cookie, cmd);
+ * if (err == LCB_SUCCESS) {
+ *     lcb_n1ql_set_parent_span(instance, handle, span);
+ * }
+ * @endcode
+ *
+ * @committed
  */
 LIBCOUCHBASE_API
 void lcb_n1ql_set_parent_span(lcb_t instance, lcb_N1QLHANDLE handle, lcbtrace_SPAN *span);
-#endif
-
-/**@}*/
-
-/**@}*/
 
+#endif
+/**
+ * @} (Group: Tracing)
+ */
 #ifdef __cplusplus
 }
 #endif

data/ext/libcouchbase/include/libcouchbase/subdoc.h

@@ -28,10 +28,6 @@ extern "C" {
  * 4.5 release which allows access to parts of the document. These parts are
  * called _sub-documents_ and can be accessed using the sub-document API
  *
- * @warning
- * The sub-document API is experimental and subject to change and is here for
- * demonstration purposes only.
- *
  * @addtogroup lcb-subdoc
  * @{
  */
@@ -113,7 +109,7 @@ typedef enum {
      * should be placed, for example `array[2]` will cause the value(s) to be
      * the 3rd item(s) in the array.
      *
-     * The array must already exist and the @ref LCB_SDCMD_F_MKINTERMEDIATES
+     * The array must already exist and the @ref LCB_SDSPEC_F_MKINTERMEDIATES
      * flag is not honored.
      */
     LCB_SDCMD_ARRAY_INSERT,
@@ -182,7 +178,7 @@ typedef struct {
     lcb_KEYBUF path;
 
     /**
-     * @value for the operation. This should be assigned using
+     * Value for the operation. This should be assigned using
      * @ref LCB_SDSPEC_SET_VALUE. The contents of the value should be valid
      * until the operation is scheduled (i.e. lcb_subdoc3())
      */
@@ -307,7 +303,7 @@ typedef struct {
  * Note that #value and #nvalue are only valid if #status is ::LCB_SUCCESS
  */
 typedef struct {
-    /** Value for the mutation (only applicable for ::LCB_SUBDOC_COUNTER, currently) */
+    /** Value for the mutation (only applicable for ::LCB_SDCMD_COUNTER, currently) */
     const void *value;
     /** Length of the value */
     size_t nvalue;

data/ext/libcouchbase/include/libcouchbase/tracing.h

@@ -22,7 +22,12 @@
  * @file
  * End to end tracing
  *
- * @uncommitted
+ * @ingroup lcb-public-api
+ * @defgroup lcb-tracing-api End to end tracing
+ * @brief Tracing operations through SDK and the Cluster.
+ *
+ * @addtogroup lcb-tracing-api
+ * @{
  */
 
 #ifdef __cplusplus
@@ -40,40 +45,62 @@ extern "C" {
 typedef struct lcbtrace_SPAN_Cdummy lcbtrace_SPAN;
 #endif
 
+/**
+ * Flag for @ref lcbtrace_new to request threshold logging tracer.
+ */
 #define LCBTRACE_F_THRESHOLD 0x01
 
 struct lcbtrace_TRACER;
+/**
+ * Tracer interface.
+ */
 typedef struct lcbtrace_TRACER {
-    lcb_U16 version;
-    lcb_U64 flags;
-    void *cookie;
-    void (*destructor)(struct lcbtrace_TRACER *tracer);
+    lcb_U16 version;                                    /**< version of the structure, current value is 0 */
+    lcb_U64 flags;                                      /**< tracer-specific flags */
+    void *cookie;                                       /**< opaque pointer (e.g. pointer to wrapper structure) */
+    void (*destructor)(struct lcbtrace_TRACER *tracer); /**< destructor function or NULL, if it is not necessary */
     union {
         struct {
-            void (*report)(struct lcbtrace_TRACER *tracer, lcbtrace_SPAN *span);
+            void (*report)(struct lcbtrace_TRACER *tracer, lcbtrace_SPAN *span); /**< optional reporter function */
         } v0;
     } v;
 } lcbtrace_TRACER;
 
 /**
- * @uncommitted
+ * Get current tracer of the connection.
+ *
+ * @param instance current connection
  * @return tracer
+ *
+ * @committed
  */
 LIBCOUCHBASE_API lcbtrace_TRACER *lcb_get_tracer(lcb_t instance);
 
 /**
- * @uncommitted
- * @return tracer
+ * Set current tracer for the connection.
+ *
+ * @param instance current connection
+ * @param tracer tracer instance
+ *
+ * @committed
  */
 LIBCOUCHBASE_API void lcb_set_tracer(lcb_t instance, lcbtrace_TRACER *tracer);
 
 /**
- * @uncommitted
+ * Create default libcouchbase tracer instance.
+ *
+ * @param instance current connection
+ * @param flags pass @ref LCBTRACE_F_THRESHOLD if needed threshold logging tracer.
+ * @return new tracer or NULL when nothing has been created.
+ *
+ * @committed
  */
 LIBCOUCHBASE_API lcbtrace_TRACER *lcbtrace_new(lcb_t instance, lcb_U64 flags);
 
 /**
- * @uncommitted
+ * Destroy tracer object.
+ *
+ * @committed
  */
 LIBCOUCHBASE_API void lcbtrace_destroy(lcbtrace_TRACER *tracer);
 
@@ -89,55 +116,86 @@ typedef struct {
     lcbtrace_SPAN *span;
 } lcbtrace_REF;
 
-#define LCBTRACE_OP_GET "get"
-
 /** zero means the library will trigger timestamp automatically */
 #define LCBTRACE_NOW 0
 
 /**
- * @return time in microseconds
+ * Get current timestamp.
+ *
+ * @return current wall clock time in microseconds
+ *
+ * @committed
  */
 LIBCOUCHBASE_API
 lcb_U64 lcbtrace_now(void);
 
 /**
- * @uncommitted
- * @param tracer
- * @param operation
- * @param now
- * @param ctx
+ * Start span.
+ *
+ * @param tracer tracer instance
+ * @param operation the operation code
+ * @param now start timestamp or @ref LCBTRACE_NOW to let the library to record current time from the wall clock.
+ * @param ref reference to the other span, or NULL
+ *
+ * @committed
  */
 LIBCOUCHBASE_API
 lcbtrace_SPAN *lcbtrace_span_start(lcbtrace_TRACER *tracer, const char *operation, lcb_U64 now, lcbtrace_REF *ref);
 
 /**
- * @uncommitted
- * @param span
- * @param now
+ * Mark the span as finished.
+ *
+ * @param span span instance
+ * @param now finish timestamp or @ref LCBTRACE_NOW to let the library to record current time from the wall clock.
+ *
+ * @committed
  */
 LIBCOUCHBASE_API
 void lcbtrace_span_finish(lcbtrace_SPAN *span, lcb_U64 now);
 
 /**
- * @uncommitted
+ * Get start timestamp of the span.
+ *
+ * @param span span instance
+ * @return timestamp in microseconds when the span has been started.
+ *
+ * @committed
  */
 LIBCOUCHBASE_API
 lcb_U64 lcbtrace_span_get_start_ts(lcbtrace_SPAN *span);
 
 /**
- * @uncommitted
+ * Get finish timestamp of the span.
+ *
+ * @param span span instance
+ * @return timestamp in microseconds when the span has been finished.
+ *
+ * @committed
  */
 LIBCOUCHBASE_API
 lcb_U64 lcbtrace_span_get_finish_ts(lcbtrace_SPAN *span);
 
 /**
- * @uncommitted
+ * Check if the span is orphaned.
+ *
+ * Spans might be marked as orphaned, when the library has discarded
+ * request structure without waiting for server response (e.g. on timeout).
+ *
+ * @param span span instance
+ * @return non-zero if span is orphaned.
+ *
+ * @committed
  */
 LIBCOUCHBASE_API
 int lcbtrace_span_is_orphaned(lcbtrace_SPAN *span);
 
 /**
- * @uncomitted
+ * Get operation code of the span.
+ *
+ * @param span span instance
+ * @return operation code
+ *
+ * @committed
  */
 LIBCOUCHBASE_API
 const char *lcbtrace_span_get_operation(lcbtrace_SPAN *span);
@@ -163,11 +221,10 @@ const char *lcbtrace_span_get_operation(lcbtrace_SPAN *span);
 #define LCBTRACE_OP_UPSERT "upsert"
 #define LCBTRACE_OP_UPSERT "upsert"
 
-#define LCBTRACE_OP_STORE2NAME(code)                \
-    (code == LCB_ADD) ? LCBTRACE_OP_ADD :           \
-    (code == LCB_PREPEND) ? LCBTRACE_OP_PREPEND :   \
-    (code == LCB_APPEND) ? LCBTRACE_OP_APPEND :     \
-    LCBTRACE_OP_UPSERT
+#define LCBTRACE_OP_STORE2NAME(code)                                                                                   \
+    (code == LCB_ADD)                                                                                                  \
+        ? LCBTRACE_OP_ADD                                                                                              \
+        : (code == LCB_PREPEND) ? LCBTRACE_OP_PREPEND : (code == LCB_APPEND) ? LCBTRACE_OP_APPEND : LCBTRACE_OP_UPSERT
 
 #define LCBTRACE_TAG_DB_TYPE "db.type"
 #define LCBTRACE_TAG_SPAN_KIND "span.kind"
@@ -215,79 +272,135 @@ const char *lcbtrace_span_get_operation(lcbtrace_SPAN *span);
 #define LCBTRACE_TAG_PEER_LATENCY "peer.latency"
 
 /**
- * @uncommitted
+ * Get ID of the span.
+ *
+ * @param span span instance
+ * @return span ID
+ *
+ * @committed
  */
 LIBCOUCHBASE_API
 lcb_U64 lcbtrace_span_get_span_id(lcbtrace_SPAN *span);
 
 /**
- * @uncommitted
+ * Get trace ID of the span.
+ *
+ * @param span span instance
+ * @return trace ID
+ *
+ * @committed
  */
 LIBCOUCHBASE_API
 lcb_U64 lcbtrace_span_get_trace_id(lcbtrace_SPAN *span);
 
 /**
- * @uncommitted
+ * Get parent span of the span.
+ *
+ * @param span span instance
+ * @return parent span or NULL
+ *
+ * @committed
  */
 LIBCOUCHBASE_API
 lcbtrace_SPAN *lcbtrace_span_get_parent(lcbtrace_SPAN *span);
 
 /**
- * @uncommitted
+ * Get value of the string tag of the span.
+ *
+ * @param span span instance
+ * @param name name of the tag
+ * @param value pointer to result string
+ * @param nvalue pointer to length of the result string
+ * @return LCB_SUCCESS if value exists and was written to result pointer
+ *
+ * @committed
  */
 LIBCOUCHBASE_API
 lcb_error_t lcbtrace_span_get_tag_str(lcbtrace_SPAN *span, const char *name, char **value, size_t *nvalue);
 
 /**
- * @uncommitted
+ * Get value of the integer tag of the span.
+ *
+ * @param span span instance
+ * @param name name of the tag
+ * @param value pointer to result
+ * @return LCB_SUCCESS if value exists and was written to result pointer
+ *
+ * @committed
  */
 LIBCOUCHBASE_API
 lcb_error_t lcbtrace_span_get_tag_uint64(lcbtrace_SPAN *span, const char *name, lcb_U64 *value);
 
 /**
- * @uncommitted
+ * Get value of the double tag of the span.
+ *
+ * @param span span instance
+ * @param name name of the tag
+ * @param value pointer to result
+ * @return LCB_SUCCESS if value exists and was written to result pointer
+ *
+ * @committed
  */
 LIBCOUCHBASE_API
 lcb_error_t lcbtrace_span_get_tag_double(lcbtrace_SPAN *span, const char *name, double *value);
 
 /**
- * @uncommitted
+ * Get value of the boolean tag of the span.
+ *
+ * @param span span instance
+ * @param name name of the tag
+ * @param value pointer to result
+ * @return LCB_SUCCESS if value exists and was written to result pointer
+ *
+ * @committed
  */
 LIBCOUCHBASE_API
-lcb_error_t lcbtrace_span_get_tag_bool(lcbtrace_SPAN *span, const char *name, int value);
+lcb_error_t lcbtrace_span_get_tag_bool(lcbtrace_SPAN *span, const char *name, int *value);
 
 /**
- * @uncommitted
- * @param span
- * @param name
- * @param value
+ * Add string tag to span.
+ *
+ * @param span span instance
+ * @param name name of the tag
+ * @param value value of the tag (NUL-terminated)
+ *
+ * @committed
  */
 LIBCOUCHBASE_API
 void lcbtrace_span_add_tag_str(lcbtrace_SPAN *span, const char *name, const char *value);
 
 /**
- * @uncommitted
- * @param span
- * @param name
- * @param value
+ * Add integer tag to span.
+ *
+ * @param span span instance
+ * @param name name of the tag
+ * @param value value of the tag
+ *
+ * @committed
  */
 LIBCOUCHBASE_API
 void lcbtrace_span_add_tag_uint64(lcbtrace_SPAN *span, const char *name, lcb_U64 value);
 
 /**
- * @uncommitted
- * @param span
- * @param name
- * @param value
+ * Add double tag to span.
+ *
+ * @param span span instance
+ * @param name name of the tag
+ * @param value value of the tag
+ *
+ * @committed
  */
 LIBCOUCHBASE_API
 void lcbtrace_span_add_tag_double(lcbtrace_SPAN *span, const char *name, double value);
 
 /**
- * @uncommitted
- * @param span
- * @param name
- * @param value
+ * Add boolean tag to span.
+ *
+ * @param span span instance
+ * @param name name of the tag
+ * @param value value of the tag. 0 if false, otherwise -- true.
+ *
+ * @committed
  */
 LIBCOUCHBASE_API
 void lcbtrace_span_add_tag_bool(lcbtrace_SPAN *span, const char *name, int value);
@@ -297,7 +410,8 @@ void lcbtrace_span_add_tag_bool(lcbtrace_SPAN *span, const char *name, int value
  *
  * @param cmd the command structure
  * @param ctx the lcbtrace_SPAN pointer
- * @uncommitted
+ *
+ * @committed
  */
 #define LCB_CMD_SET_TRACESPAN(cmd, span)                                                                               \
     do {                                                                                                               \
@@ -313,6 +427,10 @@ typedef struct {
     void (*report)(void *state, lcbtrace_SPAN *span);
 } ldcptrace_REPORTER;
 
+/**
+ * @} (Group: Tracing)
+ */
+
 #ifdef __cplusplus
 }
 #endif