Put Python plugin support in a separate shared object

[babeltrace.git] / include / babeltrace / values.h

diff --git a/include/babeltrace/values.h b/include/babeltrace/values.h
index d5ffef0b94bd0dada2201102d227e9db6799bd42..03c0024fdbc2afaf758cb9db8709afd2e1bd9656 100644 (file)
--- a/include/babeltrace/values.h
+++ b/include/babeltrace/values.h
@@ -40,6 +40,10 @@ extern "C" {
 @ingroup apiref
 @brief Value objects.
 
+@code
+#include <babeltrace/values.h>
+@endcode
+
 This is a set of <strong><em>value objects</em></strong>. With the
 functions documented here, you can create and modify:
 
@@ -143,7 +147,8 @@ to use for each value object type:
   </tr>
   <tr>
     <th>Map
-    <td>bt_value_map_create()
+    <td>bt_value_map_create()<br>
+        bt_value_map_extend()
     <td>bt_value_is_map()
     <td>bt_value_map_get()<br>
         bt_value_map_foreach()
@@ -427,7 +432,7 @@ Freezing a value object is typically used to make it immutable after
 it's built by its initial owner.
 
 @param[in] object      Value object to freeze.
-@returns               One of #bt_value_status values. If \p object
+@returns               Status code. If \p object
                        is already frozen, however, #BT_VALUE_STATUS_OK
                        is returned anyway (that is, this function never
                        returns #BT_VALUE_STATUS_FROZEN).
@@ -466,7 +471,6 @@ You can copy a frozen value object: the resulting copy is
 @prenotnull{object}
 @post <strong>On success, if the returned value object is not
        \ref bt_value_null</strong>, its reference count is 1.
-
 @postrefcountsame{object}
 */
 extern struct bt_value *bt_value_copy(const struct bt_value *object);
@@ -531,7 +535,7 @@ extern struct bt_value *bt_value_bool_create_init(bool val);
 @param[in] bool_obj    Boolean value object of which to get the
                        raw value.
 @param[out] val                Returned boolean raw value.
-@returns               One of #bt_value_status values.
+@returns               Status code.
 
 @prenotnull{bool_obj}
 @prenotnull{val}
@@ -550,7 +554,7 @@ extern enum bt_value_status bt_value_bool_get(
 @param[in] bool_obj    Boolean value object of which to set
                        the raw value.
 @param[in] val         New boolean raw value.
-@returns               One of #bt_value_status values.
+@returns               Status code.
 
 @prenotnull{bool_obj}
 @pre \p bool_obj is a boolean value object.
@@ -607,7 +611,7 @@ extern struct bt_value *bt_value_integer_create_init(int64_t val);
 @param[in] integer_obj Integer value object of which to get the
                        raw value.
 @param[out] val                Returned integer raw value.
-@returns               One of #bt_value_status values.
+@returns               Status code.
 
 @prenotnull{integer_obj}
 @prenotnull{val}
@@ -627,7 +631,7 @@ extern enum bt_value_status bt_value_integer_get(
 @param[in] integer_obj Integer value object of which to set
                        the raw value.
 @param[in] val         New integer raw value.
-@returns               One of #bt_value_status values.
+@returns               Status code.
 
 @prenotnull{integer_obj}
 @pre \p integer_obj is an integer value object.
@@ -684,7 +688,7 @@ extern struct bt_value *bt_value_float_create_init(double val);
 @param[in] float_obj   Floating point number value object of which to
                        get the raw value.
 @param[out] val                Returned floating point number raw value
-@returns               One of #bt_value_status values.
+@returns               Status code.
 
 @prenotnull{float_obj}
 @prenotnull{val}
@@ -704,7 +708,7 @@ extern enum bt_value_status bt_value_float_get(
 @param[in] float_obj   Floating point number value object of which to set
                        the raw value.
 @param[in] val         New floating point number raw value.
-@returns               One of #bt_value_status values.
+@returns               Status code.
 
 @prenotnull{float_obj}
 @pre \p float_obj is a floating point number value object.
@@ -767,7 +771,7 @@ returned string is \em not transferred to the caller.
 @param[in] string_obj  String value object of which to get the
                        raw value.
 @param[out] val                Returned string raw value.
-@returns               One of #bt_value_status values.
+@returns               Status code.
 
 @prenotnull{string_obj}
 @prenotnull{val}
@@ -789,7 +793,7 @@ On success, \p val is copied.
 @param[in] string_obj  String value object of which to set
                        the raw value.
 @param[in] val         New string raw value (copied on success).
-@returns               One of #bt_value_status values.
+@returns               Status code.
 
 @prenotnull{string_obj}
 @prenotnull{val}
@@ -868,7 +872,8 @@ extern bool bt_value_array_is_empty(const struct bt_value *array_obj);
 
 @prenotnull{array_obj}
 @pre \p array_obj is an array value object.
-@pre \p index is lesser than the size of \p array_obj.
+@pre \p index is lesser than the size of \p array_obj (see
+       bt_value_array_size()).
 @post <strong>On success, if the returned value object is not
        \ref bt_value_null</strong>, its reference count is incremented.
 @postrefcountsame{array_obj}
@@ -883,7 +888,7 @@ extern struct bt_value *bt_value_array_get(const struct bt_value *array_obj,
 @param[in] array_obj   Array value object in which to append
                        \p element_obj.
 @param[in] element_obj Value object to append.
-@returns               One of #bt_value_status values.
+@returns               Status code.
 
 @prenotnull{array_obj}
 @prenotnull{element_obj}
@@ -918,7 +923,7 @@ value object before appending it.
 
 @param[in] array_obj   Array value object in which to append \p val.
 @param[in] val         Boolean raw value to append to \p array_obj.
-@returns               One of #bt_value_status values.
+@returns               Status code.
 
 @prenotnull{array_obj}
 @pre \p array_obj is an array value object.
@@ -940,7 +945,7 @@ value object before appending it.
 
 @param[in] array_obj   Array value object in which to append \p val.
 @param[in] val         Integer raw value to append to \p array_obj.
-@returns               One of #bt_value_status values.
+@returns               Status code.
 
 @prenotnull{array_obj}
 @pre \p array_obj is an array value object.
@@ -963,7 +968,7 @@ point number value object before appending it.
 @param[in] array_obj   Array value object in which to append \p val.
 @param[in] val         Floating point number raw value to append
                        to \p array_obj.
-@returns               One of #bt_value_status values.
+@returns               Status code.
 
 @prenotnull{array_obj}
 @pre \p array_obj is an array value object.
@@ -988,7 +993,7 @@ On success, \p val is copied.
 @param[in] array_obj   Array value object in which to append \p val.
 @param[in] val         String raw value to append to \p array_obj
                        (copied on success).
-@returns               One of #bt_value_status values.
+@returns               Status code.
 
 @prenotnull{array_obj}
 @pre \p array_obj is an array value object.
@@ -1011,7 +1016,7 @@ object before appending it.
 
 @param[in] array_obj   Array value object in which to append an
                        empty array value object
-@returns               One of #bt_value_status values.
+@returns               Status code.
 
 @prenotnull{array_obj}
 @pre \p array_obj is an array value object.
@@ -1033,7 +1038,7 @@ object before appending it.
 
 @param[in] array_obj   Array value object in which to append an empty
                        map value object.
-@returns               One of #bt_value_status values.
+@returns               Status code.
 
 @prenotnull{array_obj}
 @pre \p array_obj is an array value object.
@@ -1056,12 +1061,13 @@ extern enum bt_value_status bt_value_array_append_empty_map(
                                \p array_obj.
 @param[in] element_obj         New value object at position \p index of
                                \p array_obj.
-@returns                       One of #bt_value_status values.
+@returns                       Status code.
 
 @prenotnull{array_obj}
 @prenotnull{element_obj}
 @pre \p array_obj is an array value object.
-@pre \p index is lesser than the size of \p array_obj.
+@pre \p index is lesser than the size of \p array_obj (see
+       bt_value_array_size()).
 @prehot{array_obj}
 @post <strong>On success, if the replaced value object is not
        \ref bt_value_null</strong>, its reference count is decremented.
@@ -1134,7 +1140,6 @@ extern bool bt_value_map_is_empty(const struct bt_value *map_obj);
 @prenotnull{key}
 @pre \p map_obj is a map value object.
 @postrefcountsame{map_obj}
-
 @post <strong>On success, if the returned value object is not
        \ref bt_value_null</strong>, its reference count is incremented.
 */
@@ -1145,7 +1150,7 @@ extern struct bt_value *bt_value_map_get(const struct bt_value *map_obj,
 @brief User function type to use with bt_value_map_foreach().
 
 \p object is a <em>weak reference</em>: you \em must pass it to bt_get()
-if you need your own reference.
+if you need to keep a reference after this function returns.
 
 This function \em must return \c true to continue the map value object
 traversal, or \c false to break it.
@@ -1168,7 +1173,8 @@ typedef bool (* bt_value_map_foreach_cb)(const char *key,
        map value object \p map_obj.
 
 The value object passed to the user function is a <b>weak reference</b>:
-you \em must pass it to bt_get() if you need your own reference.
+you \em must pass it to bt_get() if you need to keep a persistent
+reference after the user function returns.
 
 The key passed to the user function is only valid in the scope of
 this user function call.
@@ -1179,7 +1185,7 @@ The user function \em must return \c true to continue the traversal of
 @param[in] map_obj     Map value object on which to iterate.
 @param[in] cb          User function to call back.
 @param[in] data                User data passed to the user function.
-@returns               One of #bt_value_status values. More
+@returns               Status code. More
                        specifically, #BT_VALUE_STATUS_CANCELLED is
                        returned if the loop was cancelled by the user
                        function.
@@ -1227,7 +1233,7 @@ On success, \p key is copied.
                        value object to insert is mapped.
 @param[in] element_obj Value object to insert, mapped to the
                        key \p key.
-@returns               One of #bt_value_status values.
+@returns               Status code.
 
 @prenotnull{map_obj}
 @prenotnull{key}
@@ -1269,7 +1275,7 @@ On success, \p key is copied.
                        value object to insert is mapped.
 @param[in] val         Boolean raw value to insert, mapped to
                        the key \p key.
-@returns               One of #bt_value_status values.
+@returns               Status code.
 
 @prenotnull{map_obj}
 @prenotnull{key}
@@ -1297,7 +1303,7 @@ On success, \p key is copied.
                        value object to insert is mapped.
 @param[in] val         Integer raw value to insert, mapped to
                        the key \p key.
-@returns               One of #bt_value_status values.
+@returns               Status code.
 
 @prenotnull{map_obj}
 @prenotnull{key}
@@ -1325,7 +1331,7 @@ On success, \p key is copied.
                        point number value object to insert is mapped.
 @param[in] val         Floating point number raw value to insert,
                        mapped to the key \p key.
-@returns               One of #bt_value_status values.
+@returns               Status code.
 
 @prenotnull{map_obj}
 @prenotnull{key}
@@ -1353,7 +1359,7 @@ On success, \p val and \p key are copied.
                        value object to insert is mapped.
 @param[in] val         String raw value to insert (copied on success),
                        mapped to the key \p key.
-@returns               One of #bt_value_status values.
+@returns               Status code.
 
 @prenotnull{map_obj}
 @prenotnull{key}
@@ -1381,7 +1387,7 @@ On success, \p key is copied.
                        array value object.
 @param[in] key         Key (copied on success) to which the empty array
                        value object to insert is mapped.
-@returns               One of #bt_value_status values.
+@returns               Status code.
 
 @prenotnull{map_obj}
 @prenotnull{key}
@@ -1408,7 +1414,7 @@ On success, \p key is copied.
                        map object.
 @param[in] key         Key (copied on success) to which the empty map
                        value object to insert is mapped.
-@returns               One of #bt_value_status values.
+@returns               Status code.
 
 @prenotnull{map_obj}
 @prenotnull{key}
@@ -1435,28 +1441,28 @@ value objects.
 
 For example, consider the following \p base_map_obj (JSON representation):
 
-@code{.unparsed}
+@verbatim
 {
   "hello": 23,
   "code": -17,
   "em": false,
   "return": [5, 6, null]
 }
-@endcode
+@endverbatim
 
 and the following \p extension_map_obj (JSON representation):
 
-@code{.unparsed}
+@verbatim
 {
   "comma": ",",
   "code": 22,
   "return": 17.88
 }
-@endcode
+@endverbatim
 
 The extended object is (JSON representation):
 
-@code{.unparsed}
+@verbatim
 {
   "hello": 23,
   "code": 22,
@@ -1464,7 +1470,7 @@ The extended object is (JSON representation):
   "return": 17.88,
   "comma": ","
 }
-@endcode
+@endverbatim
 
 @param[in] base_map_obj                Base map value object with initial
                                entries.