- * Value object type.
- */
-enum bt_value_type {
- /** Unknown value object, used as an error code. */
- BT_VALUE_TYPE_UNKNOWN = -1,
-
- /** Null value object. */
- BT_VALUE_TYPE_NULL = 0,
-
- /** Boolean value object (holds \c true or \c false). */
- BT_VALUE_TYPE_BOOL = 1,
-
- /** Integer value object (holds a signed 64-bit integer raw value). */
- BT_VALUE_TYPE_INTEGER = 2,
-
- /** Floating point number value object (holds a \c double raw value). */
- BT_VALUE_TYPE_FLOAT = 3,
-
- /** String value object. */
- BT_VALUE_TYPE_STRING = 4,
-
- /** Array value object. */
- BT_VALUE_TYPE_ARRAY = 5,
-
- /** Map value object. */
- BT_VALUE_TYPE_MAP = 6,
-};
+@defgroup values Value objects
+@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:
+
+- \link bt_value_bool_create() Boolean value objects\endlink.
+- \link bt_value_integer_create() Integer value objects\endlink.
+- \link bt_value_float_create() Floating point number
+ value objects\endlink.
+- \link bt_value_string_create() String value objects\endlink.
+- \link bt_value_array_create() Array value objects\endlink,
+ containing zero or more value objects.
+- \link bt_value_map_create() Map value objects\endlink, mapping
+ string keys to value objects.
+
+As with any Babeltrace object, value objects have
+<a href="https://en.wikipedia.org/wiki/Reference_counting">reference
+counts</a>. When you \link bt_value_array_append() append a value object
+to an array value object\endlink, or when you \link bt_value_map_insert()
+insert a value object into a map value object\endlink, its reference
+count is incremented, as well as when you get a value object back from
+those objects. See \ref refs to learn more about the reference counting
+management of Babeltrace objects.
+
+Most functions of this API return a <em>status code</em>, one of the
+values of #bt_value_status.
+
+You can create a deep copy of any value object with bt_value_copy(). You
+can compare two value objects with bt_value_compare().
+
+You can \em freeze a value object with bt_value_freeze(). You can get
+the raw value of a frozen value object, but you cannot modify it.
+Reference counting still works on frozen value objects. You can copy
+a frozen value object: the returned copy is not frozen. You can also
+compare a frozen value object to another value object (frozen or not).
+Freezing a value object is typically used to make it immutable after
+it's built by its initial owner.
+
+The following matrix shows some categorized value object functions
+to use for each value object type:
+
+<table>
+ <tr>
+ <th>Function role →<br>
+ Value object type ↓
+ <th>Create
+ <th>Check type
+ <th>Get value
+ <th>Set value
+ </tr>
+ <tr>
+ <th>Null
+ <td>Use the \ref bt_value_null variable
+ <td>bt_value_is_null()
+ <td>N/A
+ <td>N/A
+ </tr>
+ <tr>
+ <th>Boolean
+ <td>bt_value_bool_create()<br>
+ bt_value_bool_create_init()
+ <td>bt_value_is_bool()
+ <td>bt_value_bool_get()
+ <td>bt_value_bool_set()
+ </tr>
+ <tr>
+ <th>Integer
+ <td>bt_value_integer_create()<br>
+ bt_value_integer_create_init()
+ <td>bt_value_is_integer()
+ <td>bt_value_integer_get()
+ <td>bt_value_integer_set()
+ </tr>
+ <tr>
+ <th>Floating point<br>number
+ <td>bt_value_float_create()<br>
+ bt_value_float_create_init()
+ <td>bt_value_is_float()
+ <td>bt_value_float_get()
+ <td>bt_value_float_set()
+ </tr>
+ <tr>
+ <th>String
+ <td>bt_value_string_create()<br>
+ bt_value_string_create_init()
+ <td>bt_value_is_string()
+ <td>bt_value_string_get()
+ <td>bt_value_string_set()
+ </tr>
+ <tr>
+ <th>Array
+ <td>bt_value_array_create()
+ <td>bt_value_is_array()
+ <td>bt_value_array_get()
+ <td>bt_value_array_append()<br>
+ bt_value_array_append_bool()<br>
+ bt_value_array_append_integer()<br>
+ bt_value_array_append_float()<br>
+ bt_value_array_append_string()<br>
+ bt_value_array_append_empty_array()<br>
+ bt_value_array_append_empty_map()<br>
+ bt_value_array_set()
+ </tr>
+ <tr>
+ <th>Map
+ <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()
+ <td>bt_value_map_insert()<br>
+ bt_value_map_insert_bool()<br>
+ bt_value_map_insert_integer()<br>
+ bt_value_map_insert_float()<br>
+ bt_value_map_insert_string()<br>
+ bt_value_map_insert_empty_array()<br>
+ bt_value_map_insert_empty_map()
+ </tr>
+</table>
+
+@file
+@brief Value object types and functions.
+@sa values
+
+@addtogroup values
+@{
+*/