X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=blobdiff_plain;f=include%2Fbabeltrace2%2Ftrace-ir%2Ffield.h;h=572118eedb05c3744adc155a51d7e886a5e9fe29;hp=f95298deec5f75c748e1c130a1485fc4173a290a;hb=43c59509042845f8d42c3e99ec74d45fa2dc0908;hpb=1cda4ff4025e4b3f7bd2a861baa51d2113c4cbf9

diff --git a/include/babeltrace2/trace-ir/field.h b/include/babeltrace2/trace-ir/field.h
index f95298de..572118ee 100644
--- a/include/babeltrace2/trace-ir/field.h
+++ b/include/babeltrace2/trace-ir/field.h
@@ -35,79 +35,1502 @@
 extern "C" {
 #endif
 
+/*!
+@defgroup api-tir-field Fields
+@ingroup api-tir
+
+@brief
+    Containers of trace data.
+
+<strong><em>Fields</em></strong> are containers of trace data: they are
+found in \bt_p_ev and \bt_p_pkt.
+
+Fields are instances of \bt_p_fc:
+
+@image html field-class-zoom.png
+
+Borrow the class of a field with bt_field_borrow_class() and
+bt_field_borrow_class_const().
+
+Fields are \ref api-tir "trace IR" data objects.
+
+There are many types of fields. They can be divided into two main
+categories:
+
+<dl>
+  <dt>Scalar</dt>
+  <dd>
+    Fields which contain a simple value.
+
+    The scalar fields are:
+
+    - \ref api-tir-field-bool "Boolean"
+    - \ref api-tir-field-ba "Bit array"
+    - \ref api-tir-field-int "Integer" (unsigned and signed)
+    - \ref api-tir-field-enum "Enumeration" (unsigned and signed)
+    - \ref api-tir-field-real "Real" (single-precision and double-precision)
+    - \ref api-tir-field-string "String"
+  </dd>
+
+  <dt>Container</dt>
+  <dd>
+    Fields which contain other fields.
+
+    The container fields are:
+
+    - \ref api-tir-field-array "Array" (static and dynamic)
+    - \ref api-tir-field-struct "Structure"
+    - \ref api-tir-field-opt "Option"
+    - \ref api-tir-field-var "Variant"
+  </dd>
+</dl>
+
+@image html fc-to-field.png "Fields (green) are instances of field classes (orange)."
+
+You cannot directly create a field: there are no
+<code>bt_field_*_create()</code> functions. The \bt_name library
+creates fields within an \bt_ev or a \bt_pkt from \bt_p_fc.
+Therefore, to fill the payload fields of an \bt_ev, you must first
+borrow the event's existing payload \bt_struct_field with
+bt_event_borrow_payload_field() and then borrow each field, recursively,
+to set their values.
+
+The functions to borrow a field from an event or a packet are:
+
+- bt_packet_borrow_context_field() and
+  bt_packet_borrow_context_field_const()
+- bt_event_borrow_common_context_field() and
+  bt_event_borrow_common_context_field_const()
+- bt_event_borrow_specific_context_field() and
+  bt_event_borrow_specific_context_field_const()
+- bt_event_borrow_payload_field() and
+  bt_event_borrow_payload_field_const()
+
+Some fields conceptually inherit other fields, eventually
+making an inheritance hierarchy. For example, an \bt_enum_field
+\em is an \bt_int_field. Therefore, an enumeration field holds an
+integral value, just like an integer field does.
+
+The complete field inheritance hierarchy is:
+
+@image html all-fields.png
+
+This is the same inheritance hierarchy as the \bt_fc inheritance
+hierarchy.
+
+In the illustration above:
+
+- A field with a dark background is instantiated from a concrete \bt_fc,
+  which you can directly create with a dedicated
+  <code>bt_field_class_*_create()</code> function.
+
+- A field with a pale background is an \em abstract field: it's not a
+  concrete instance, but it can have properties, therefore there can be
+  functions which apply to it.
+
+  For example, bt_field_integer_signed_set_value() applies to any
+  \bt_sint_field.
+
+Fields are \ref api-fund-unique-object "unique objects": they belong
+to an \bt_ev or to a \bt_pkt.
+
+Some library functions \ref api-fund-freezing "freeze" fields on
+success. The documentation of those functions indicate this
+postcondition.
+
+All the field types share the same C type, #bt_field.
+
+Get the type enumerator of a field's class with bt_field_get_class_type().
+Get whether or not a field class type conceptually \em is a given type
+with the inline bt_field_class_type_is() function.
+
+<h1>\anchor api-tir-field-bool Boolean field</h1>
+
+A <strong><em>boolean field</em></strong> is a \bt_bool_fc instance.
+
+A boolean field contains a boolean value (#BT_TRUE or #BT_FALSE).
+
+Set the value of a boolean field with bt_field_bool_set_value().
+
+Get the value of a boolean field with bt_field_bool_get_value().
+
+<h1>\anchor api-tir-field-ba Bit array field</h1>
+
+A <strong><em>bit array field</em></strong> is a \bt_ba_fc instance.
+
+A bit array field contains a fixed-length array of bits. Its length
+is \ref api-tir-fc-ba-prop-len "given by its class".
+
+The bit array field API interprets the array as an unsigned integer
+value: the least significant bit's index is 0.
+
+For example, to get whether or not bit&nbsp;3 of a bit array field is
+set:
+
+@code
+uint64_t value = bt_field_bit_array_get_value_as_integer(field);
+
+if (value & (UINT64_C(1) << UINT64_C(3))) {
+    // Bit 3 is set
+}
+@endcode
+
+Set the bits of a bit array field with
+bt_field_bit_array_set_value_as_integer().
+
+Get the bits of a bit array field with
+bt_field_bit_array_get_value_as_integer().
+
+<h1>\anchor api-tir-field-int Integer fields</h1>
+
+<strong><em>Integer fields</em></strong> are \bt_int_fc instances.
+
+Integer fields contain integral values.
+
+An integer field is an \em abstract field. The concrete integer fields
+are:
+
+<dl>
+  <dt>Unsigned integer field</dt>
+  <dd>
+    An \bt_uint_fc instance.
+
+    An unsigned integer field contains an unsigned integral value
+    (\c uint64_t).
+
+    Set the value of an unsigned integer field with
+    bt_field_integer_unsigned_set_value().
+
+    Get the value of an unsigned integer field with
+    bt_field_integer_unsigned_get_value().
+  </dd>
+
+  <dt>Signed integer field</dt>
+  <dd>
+    A \bt_sint_fc instance.
+
+    A signed integer field contains a signed integral value (\c int64_t).
+
+    Set the value of a signed integer field with
+    bt_field_integer_signed_set_value().
+
+    Get the value of a signed integer field with
+    bt_field_integer_signed_get_value().
+  </dd>
+</dl>
+
+<h2>\anchor api-tir-field-enum Enumeration fields</h2>
+
+<strong><em>Enumeration fields</em></strong> are \bt_enum_fc instances.
+
+Enumeration fields \em are \bt_p_int_field: they contain integral
+values.
+
+An enumeration field is an \em abstract field.
+The concrete enumeration fields are:
+
+<dl>
+  <dt>Unsigned enumeration field</dt>
+  <dd>
+    An \bt_uenum_fc instance.
+
+    An unsigned enumeration field contains an unsigned integral value
+    (\c uint64_t).
+
+    Set the value of an unsigned enumeration field with
+    bt_field_integer_unsigned_set_value().
+
+    Get the value of an unsigned enumeration field with
+    bt_field_integer_unsigned_get_value().
+
+    Get all the enumeration field class labels mapped to the value of a
+    given unsigned enumeration field with
+    bt_field_enumeration_unsigned_get_mapping_labels().
+  </dd>
+
+  <dt>Signed enumeration field</dt>
+  <dd>
+    A \bt_senum_fc instance.
+
+    A signed enumeration field contains a signed integral value
+    (\c int64_t).
+
+    Set the value of a signed enumeration field with
+    bt_field_integer_signed_set_value().
+
+    Get the value of a signed enumeration field with
+    bt_field_integer_signed_get_value().
+
+    Get all the enumeration field class labels mapped to the value of a
+    given signed enumeration field with
+    bt_field_enumeration_signed_get_mapping_labels().
+  </dd>
+</dl>
+
+<h1>\anchor api-tir-field-real Real fields</h1>
+
+<strong><em>Real fields</em></strong> are \bt_real_fc instances.
+
+Real fields contain
+<a href="https://en.wikipedia.org/wiki/Real_number">real</a>
+values (\c float or \c double types).
+
+A real field is an \em abstract field. The concrete real fields are:
+
+<dl>
+  <dt>Single-precision real field</dt>
+  <dd>
+    A single-precision real field class instance.
+
+    A single-precision real field contains a \c float value.
+
+    Set the value of a single-precision real field with
+    bt_field_real_single_precision_set_value().
+
+    Get the value of a single-precision real field with
+    bt_field_real_single_precision_get_value().
+  </dd>
+
+  <dt>Double-precision real field</dt>
+  <dd>
+    A double-precision real field class instance.
+
+    A double-precision real field contains a \c double value.
+
+    Set the value of a double-precision real field with
+    bt_field_real_double_precision_set_value().
+
+    Get the value of a double-precision real field with
+    bt_field_real_double_precision_get_value().
+  </dd>
+</dl>
+
+<h1>\anchor api-tir-field-string String field</h1>
+
+A <strong><em>string field</em></strong> is a \bt_string_fc instance.
+
+A string field contains an UTF-8 string value.
+
+Set the value of a string field with
+bt_field_string_set_value().
+
+Get the value of a string field with
+bt_field_string_get_value().
+
+Get the length of a string field with
+bt_field_string_get_length().
+
+Append a string to a string field's current value with
+bt_field_string_append() and bt_field_string_append_with_length().
+
+Clear a string field with bt_field_string_clear().
+
+<h1>\anchor api-tir-field-array Array fields</h1>
+
+<strong><em>Array fields</em></strong> are \bt_array_fc instances.
+
+Array fields contain zero or more fields which have the same class.
+
+An array field is an \em abstract field. The concrete array fields are:
+
+<dl>
+  <dt>Static array field</dt>
+  <dd>
+    A \bt_sarray_fc instance.
+
+    A static array field contains a fixed number of fields. Its length
+    is \ref api-tir-fc-sarray-prop-len "given by its class".
+  </dd>
+
+  <dt>Dynamic array field class</dt>
+  <dd>
+    A \bt_darray_fc instance.
+
+    A dynamic array field contains a variable number of fields, that is,
+    each instance of the same dynamic array field class can contain a
+    different number of elements.
+
+    Set a dynamic array field's length with
+    bt_field_array_dynamic_set_length() before you borrow any of its
+    fields.
+  </dd>
+</dl>
+
+Get an array field's length with bt_field_array_get_length().
+
+Borrow a field from an array field at a given index with
+bt_field_array_borrow_element_field_by_index() and
+bt_field_array_borrow_element_field_by_index_const().
+
+<h1>\anchor api-tir-field-struct Structure field</h1>
+
+A <strong><em>structure field</em></strong> is a \bt_struct_fc instance.
+
+A structure field contains an ordered list of zero or more members. A
+structure field member contains a field: it's an instance of a structure
+field class member.
+
+Borrow a member's field from a structure field at a given index with
+bt_field_structure_borrow_member_field_by_index() and
+bt_field_structure_borrow_member_field_by_index_const().
+
+Borrow a member's field from a structure field by name with
+bt_field_structure_borrow_member_field_by_name() and
+bt_field_structure_borrow_member_field_by_name_const().
+
+<h1>\anchor api-tir-field-opt Option field</h1>
+
+An <strong><em>option field</em></strong> is an \bt_opt_fc instance.
+
+An option field either does or doesn't contain a field.
+
+Set whether or not an option field has a field with
+bt_field_option_set_has_field().
+
+Borrow the field from an option field with
+bt_field_option_borrow_field() or
+bt_field_option_borrow_field_const().
+
+<h1>\anchor api-tir-field-var Variant field</h1>
+
+A <strong><em>variant field</em></strong> is a \bt_var_fc instance.
+
+A variant field has a single selected option amongst one or more
+possible options. A variant field option contains a field: it's an
+instance of a variant field class option.
+
+Set the current option of a variant field with
+bt_field_variant_select_option_by_index().
+
+Get a variant field's selected option's index with
+bt_field_variant_get_selected_option_index().
+
+Borrow a variant field's selected option's field with
+bt_field_variant_borrow_selected_option_field() and
+bt_field_variant_borrow_selected_option_field_const().
+
+Borrow the class of a variant field's selected
+option with bt_field_variant_borrow_selected_option_class_const(),
+bt_field_variant_with_selector_field_integer_unsigned_borrow_selected_option_class_const(),
+and
+bt_field_variant_with_selector_field_integer_signed_borrow_selected_option_class_const().
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_field bt_field;
+
+@brief
+    Field.
+
+@}
+*/
+
+/*!
+@name Type query
+@{
+*/
+
+/*!
+@brief
+    Returns the type enumerator of the \ref api-tir-fc "class" of the
+    field \bt_p{field}.
+
+This function returns
+
+@code
+bt_field_class_get_type(bt_field_borrow_class(field))
+@endcode
+
+@param[in] field
+    Field of which to get the class's type enumerator
+
+@returns
+    Type enumerator of the class of \bt_p{field}.
+
+@bt_pre_not_null{field}
+
+@sa bt_field_class_get_type() &mdash;
+    Returns the type enumerator of a \bt_fc.
+*/
+extern bt_field_class_type bt_field_get_class_type(
+		const bt_field *field);
+
+/*! @} */
+
+/*!
+@name Class access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \ref api-tir-fc "class" of the field \bt_p{field}.
+
+@param[in] field
+    Field of which to borrow the class.
+
+@returns
+    \em Borrowed reference of the class of \bt_p{field}.
+
+@bt_pre_not_null{field}
+
+@sa bt_field_borrow_class_const() &mdash;
+    \c const version of this function.
+*/
 extern bt_field_class *bt_field_borrow_class(bt_field *field);
 
+/*!
+@brief
+    Borrows the \ref api-tir-fc "class" of the field \bt_p{field}
+    (\c const version).
+
+See bt_field_borrow_class().
+*/
+extern const bt_field_class *bt_field_borrow_class_const(
+		const bt_field *field);
+
+/*! @} */
+
+/*!
+@name Boolean field
+@{
+*/
+
+/*!
+@brief
+    Sets the value of the \bt_bool_field \bt_p{field} to
+    \bt_p{value}.
+
+@param[in] field
+    Boolean field of which to set the value to \bt_p{value}.
+@param[in] value
+    New value of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_bool_field{field}
+@bt_pre_hot{field}
+
+@sa bt_field_bool_get_value() &mdash;
+    Returns the value of a boolean field.
+*/
 extern void bt_field_bool_set_value(bt_field *field, bt_bool value);
 
+/*!
+@brief
+    Returns the value of the \bt_bool_field \bt_p{field}.
+
+@param[in] field
+    Boolean field of which to get the value.
+
+@returns
+    Value of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_bool_field{field}
+
+@sa bt_field_bool_set_value() &mdash;
+    Sets the value of a boolean field.
+*/
+extern bt_bool bt_field_bool_get_value(const bt_field *field);
+
+/*! @} */
+
+/*!
+@name Bit array field
+@{
+*/
+
+/*!
+@brief
+    Sets the bits of the \bt_ba_field \bt_p{field} to the bits of
+    \bt_p{bits}.
+
+The least significant bit's index is 0.
+
+See \bt_c_ba_field to learn more.
+
+@param[in] field
+    Bit array field of which to set the bits to \bt_p{bits}.
+@param[in] bits
+    New bits of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_ba_field{field}
+@bt_pre_hot{field}
+
+@sa bt_field_bit_array_get_value_as_integer() &mdash;
+    Returns the bits of a bit array field as an integer.
+*/
 extern void bt_field_bit_array_set_value_as_integer(bt_field *field,
+		uint64_t bits);
+
+/*!
+@brief
+    Returns the bits of the \bt_ba_field \bt_p{field} as an
+    unsigned integer.
+
+The least significant bit's index is 0.
+
+See \bt_c_ba_field to learn more.
+
+@param[in] field
+    Bit array field of which to get the bits.
+
+@returns
+    Bits of \bt_p{field} as an unsigned integer.
+
+@bt_pre_not_null{field}
+@bt_pre_is_ba_field{field}
+
+@sa bt_field_bit_array_set_value_as_integer() &mdash;
+    Sets the bits of a bit array field from an integer.
+*/
+extern uint64_t bt_field_bit_array_get_value_as_integer(
+		const bt_field *field);
+
+/*! @} */
+
+/*!
+@name Integer field
+@{
+*/
+
+/*!
+@brief
+    Sets the value of the \bt_uint_field \bt_p{field} to
+    \bt_p{value}.
+
+@param[in] field
+    Unsigned integer field of which to set the value to \bt_p{value}.
+@param[in] value
+    New value of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_uint_field{field}
+@bt_pre_hot{field}
+@pre
+    \bt_p{value} is within the
+    \ref api-tir-fc-int-prop-size "field value range" of the
+    class of \bt_p{field}.
+
+@sa bt_field_integer_unsigned_get_value() &mdash;
+    Returns the value of an unsigned integer field.
+*/
+extern void bt_field_integer_unsigned_set_value(bt_field *field,
 		uint64_t value);
 
+/*!
+@brief
+    Returns the value of the \bt_uint_field \bt_p{field}.
+
+@param[in] field
+    Unsigned integer field of which to get the value.
+
+@returns
+    Value of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_uint_field{field}
+
+@sa bt_field_integer_unsigned_set_value() &mdash;
+    Sets the value of an unsigned integer field.
+*/
+extern uint64_t bt_field_integer_unsigned_get_value(
+		const bt_field *field);
+
+/*!
+@brief
+    Sets the value of the \bt_sint_field \bt_p{field} to
+    \bt_p{value}.
+
+@param[in] field
+    Signed integer field of which to set the value to \bt_p{value}.
+@param[in] value
+    New value of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_sint_field{field}
+@bt_pre_hot{field}
+@pre
+    \bt_p{value} is within the
+    \ref api-tir-fc-int-prop-size "field value range" of the
+    class of \bt_p{field}.
+
+@sa bt_field_integer_signed_get_value() &mdash;
+    Returns the value of an signed integer field.
+*/
 extern void bt_field_integer_signed_set_value(bt_field *field,
 		int64_t value);
 
-extern void bt_field_integer_unsigned_set_value(bt_field *field,
-		uint64_t value);
+/*!
+@brief
+    Returns the value of the \bt_sint_field \bt_p{field}.
+
+@param[in] field
+    Signed integer field of which to get the value.
+
+@returns
+    Value of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_sint_field{field}
+
+@sa bt_field_integer_signed_set_value() &mdash;
+    Sets the value of an signed integer field.
+*/
+extern int64_t bt_field_integer_signed_get_value(const bt_field *field);
+
+/*! @} */
+
+/*!
+@name Enumeration field
+@{
+*/
+
+/*!
+@brief
+    Status codes for
+    bt_field_enumeration_unsigned_get_mapping_labels() and
+    bt_field_enumeration_signed_get_mapping_labels().
+*/
+typedef enum bt_field_enumeration_get_mapping_labels_status {
+	/*!
+	@brief
+	    Success.
+	*/
+	BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK		= __BT_FUNC_STATUS_OK,
+
+	/*!
+	@brief
+	    Out of memory.
+	*/
+	BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR	= __BT_FUNC_STATUS_MEMORY_ERROR,
+} bt_field_enumeration_get_mapping_labels_status;
+
+/*!
+@brief
+    Returns an array of all the labels of the mappings of the
+    \ref api-tir-fc-enum "class" of the \bt_uenum_field \bt_p{field}
+    of which the \bt_p_uint_rg contain the integral value
+    of \bt_p{field}.
+
+This function returns
+
+@code
+(bt_field_enumeration_get_mapping_labels_status)
+bt_field_class_enumeration_unsigned_get_mapping_labels_for_value(
+    bt_field_borrow_class_const(field),
+    bt_field_integer_unsigned_get_value(field),
+    labels, count)
+@endcode
+
+@param[in] field
+    Unsigned enumeration field having the class from which to get the
+    labels of the mappings of which the ranges contain its
+    integral value.
+@param[out] labels
+    See
+    bt_field_class_enumeration_unsigned_get_mapping_labels_for_value().
+@param[out] count
+    See
+    bt_field_class_enumeration_unsigned_get_mapping_labels_for_value().
+
+@retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK
+    Success.
+@retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{field}
+@bt_pre_is_uenum_field{field}
+@bt_pre_not_null{labels}
+@bt_pre_not_null{count}
+*/
+extern bt_field_enumeration_get_mapping_labels_status
+bt_field_enumeration_unsigned_get_mapping_labels(const bt_field *field,
+		bt_field_class_enumeration_mapping_label_array *labels,
+		uint64_t *count);
+
+/*!
+@brief
+    Returns an array of all the labels of the mappings of the
+    \ref api-tir-fc-enum "class" of the \bt_senum_field \bt_p{field}
+    of which the \bt_p_sint_rg contain the integral value
+    of \bt_p{field}.
+
+This function returns
 
+@code
+(bt_field_enumeration_get_mapping_labels_status)
+bt_field_class_enumeration_signed_get_mapping_labels_for_value(
+    bt_field_borrow_class_const(field),
+    bt_field_integer_signed_get_value(field),
+    labels, count)
+@endcode
+
+@param[in] field
+    Signed enumeration field having the class from which to get the
+    labels of the mappings of which the ranges contain its
+    integral value.
+@param[out] labels
+    See
+    bt_field_class_enumeration_signed_get_mapping_labels_for_value().
+@param[out] count
+    See
+    bt_field_class_enumeration_signed_get_mapping_labels_for_value().
+
+@retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK
+    Success.
+@retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{field}
+@bt_pre_is_senum_field{field}
+@bt_pre_not_null{labels}
+@bt_pre_not_null{count}
+*/
+extern bt_field_enumeration_get_mapping_labels_status
+bt_field_enumeration_signed_get_mapping_labels(const bt_field *field,
+		bt_field_class_enumeration_mapping_label_array *labels,
+		uint64_t *count);
+
+/*! @} */
+
+/*!
+@name Real field
+@{
+*/
+
+/*!
+@brief
+    Sets the value of the \bt_sreal_field \bt_p{field} to
+    \bt_p{value}.
+
+@param[in] field
+    Single-precision real field of which to set the value to
+    \bt_p{value}.
+@param[in] value
+    New value of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_sreal_field{field}
+@bt_pre_hot{field}
+
+@sa bt_field_real_single_precision_get_value() &mdash;
+    Returns the value of a single-precision real field.
+*/
 extern void bt_field_real_single_precision_set_value(bt_field *field,
 		float value);
 
+/*!
+@brief
+    Returns the value of the \bt_sreal_field \bt_p{field}.
+
+@param[in] field
+    Single-precision real field of which to get the value.
+
+@returns
+    Value of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_sreal_field{field}
+
+@sa bt_field_real_single_precision_set_value() &mdash;
+    Sets the value of a single-precision real field.
+*/
+extern float bt_field_real_single_precision_get_value(const bt_field *field);
+
+/*!
+@brief
+    Sets the value of the \bt_dreal_field \bt_p{field} to
+    \bt_p{value}.
+
+@param[in] field
+    Double-precision real field of which to set the value to
+    \bt_p{value}.
+@param[in] value
+    New value of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_dreal_field{field}
+@bt_pre_hot{field}
+
+@sa bt_field_real_double_precision_get_value() &mdash;
+    Returns the value of a double-precision real field.
+*/
 extern void bt_field_real_double_precision_set_value(bt_field *field,
 		double value);
 
+/*!
+@brief
+    Returns the value of the \bt_dreal_field \bt_p{field}.
+
+@param[in] field
+    Double-precision real field of which to get the value.
+
+@returns
+    Value of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_dreal_field{field}
+
+@sa bt_field_real_double_precision_set_value() &mdash;
+    Sets the value of a double-precision real field.
+*/
+extern double bt_field_real_double_precision_get_value(const bt_field *field);
+
+/*! @} */
+
+/*!
+@name String field
+@{
+*/
+
+/*!
+@brief
+    Status codes for bt_field_string_set_value().
+*/
 typedef enum bt_field_string_set_value_status {
-	BT_FIELD_STRING_SET_VALUE_STATUS_MEMORY_ERROR	= __BT_FUNC_STATUS_MEMORY_ERROR,
+	/*!
+	@brief
+	    Success.
+	*/
 	BT_FIELD_STRING_SET_VALUE_STATUS_OK		= __BT_FUNC_STATUS_OK,
+
+	/*!
+	@brief
+	    Out of memory.
+	*/
+	BT_FIELD_STRING_SET_VALUE_STATUS_MEMORY_ERROR	= __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_field_string_set_value_status;
 
+/*!
+@brief
+    Sets the value of the \bt_string_field \bt_p{field} to
+    a copy of \bt_p{value}.
+
+@param[in] field
+    String field of which to set the value to \bt_p{value}.
+@param[in] value
+    New value of \bt_p{field} (copied).
+
+@retval #BT_FIELD_STRING_SET_VALUE_STATUS_OK
+    Success.
+@retval #BT_FIELD_STRING_SET_VALUE_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{field}
+@bt_pre_is_string_field{field}
+@bt_pre_hot{field}
+@bt_pre_not_null{value}
+
+@sa bt_field_string_get_value() &mdash;
+    Returns the value of a string field.
+@sa bt_field_string_append() &mdash;
+    Appends a string to a string field.
+@sa bt_field_string_clear() &mdash;
+    Clears a string field.
+*/
 extern bt_field_string_set_value_status bt_field_string_set_value(
 		bt_field *field, const char *value);
 
+/*!
+@brief
+    Returns the length of the \bt_string_field \bt_p{field}.
+
+@param[in] field
+    String field of which to get the length.
+
+@returns
+    Length of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_string_field{field}
+*/
+extern uint64_t bt_field_string_get_length(const bt_field *field);
+
+/*!
+@brief
+    Returns the value of the \bt_string_field \bt_p{field}.
+
+@param[in] field
+    String field of which to get the value.
+
+@returns
+    @parblock
+    Value of \bt_p{field}.
+
+    The returned pointer remains valid until \bt_p{field} is modified.
+    @endparblock
+
+@bt_pre_not_null{field}
+@bt_pre_is_string_field{field}
+
+@sa bt_field_string_set_value() &mdash;
+    Sets the value of a string field.
+*/
+extern const char *bt_field_string_get_value(const bt_field *field);
+
+/*!
+@brief
+    Status codes for bt_field_string_append() and
+    bt_field_string_append_with_length().
+*/
 typedef enum bt_field_string_append_status {
-	BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR	= __BT_FUNC_STATUS_MEMORY_ERROR,
+	/*!
+	@brief
+	    Success.
+	*/
 	BT_FIELD_STRING_APPEND_STATUS_OK		= __BT_FUNC_STATUS_OK,
+
+	/*!
+	@brief
+	    Out of memory.
+	*/
+	BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR	= __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_field_string_append_status;
 
+/*!
+@brief
+    Appends a copy of the string \bt_p{value} to the current value of
+    the \bt_string_field \bt_p{field}.
+
+@attention
+    If you didn't set the value of \bt_p{field} yet, you must call
+    bt_field_string_clear() before you call this function.
+
+@param[in] field
+    String field to which to append the string \bt_p{value}.
+@param[in] value
+    String to append to \bt_p{field} (copied).
+
+@retval #BT_FIELD_STRING_APPEND_STATUS_OK
+    Success.
+@retval #BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{field}
+@bt_pre_is_string_field{field}
+@bt_pre_hot{field}
+@bt_pre_not_null{value}
+
+@sa bt_field_string_append_with_length() &mdash;
+    Appends a string with a given length to a string field.
+@sa bt_field_string_set_value() &mdash;
+    Sets the value of a string field.
+*/
 extern bt_field_string_append_status bt_field_string_append(
 		bt_field *field, const char *value);
 
+/*!
+@brief
+    Appends a copy of the first \bt_p{length} bytes of the string
+    \bt_p{value} to the current value of the \bt_string_field
+    \bt_p{field}.
+
+@attention
+    If you didn't set the value of \bt_p{field} yet, you must call
+    bt_field_string_clear() before you call this function.
+
+@param[in] field
+    String field to which to append the first \bt_p{length} bytes of
+    the string \bt_p{value}.
+@param[in] value
+    String of which to append the first \bt_p{length} bytes to
+    \bt_p{field} (copied).
+@param[in] length
+    Number of bytes of \bt_p{value} to append to \bt_p{field}.
+
+@retval #BT_FIELD_STRING_APPEND_STATUS_OK
+    Success.
+@retval #BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{field}
+@bt_pre_is_string_field{field}
+@bt_pre_hot{field}
+@bt_pre_not_null{value}
+
+@sa bt_field_string_append() &mdash;
+    Appends a string to a string field.
+@sa bt_field_string_set_value() &mdash;
+    Sets the value of a string field.
+*/
 extern bt_field_string_append_status bt_field_string_append_with_length(
 		bt_field *field, const char *value, uint64_t length);
 
+/*!
+@brief
+    Clears the \bt_string_field \bt_p{field}, making its value an empty
+    string.
+
+@param[in] field
+    String field to clear.
+
+@bt_pre_not_null{field}
+@bt_pre_is_string_field{field}
+@bt_pre_hot{field}
+
+@sa bt_field_string_set_value() &mdash;
+    Sets the value of a string field.
+*/
 extern void bt_field_string_clear(bt_field *field);
 
-extern bt_field *bt_field_structure_borrow_member_field_by_index(
-		bt_field *field, uint64_t index);
+/*! @} */
 
-extern bt_field *bt_field_structure_borrow_member_field_by_name(
-		bt_field *field, const char *name);
+/*!
+@name Array field
+@{
+*/
+
+/*!
+@brief
+    Returns the length of the \bt_array_field \bt_p{field}.
+
+@param[in] field
+    Array field of which to get the length.
+
+@returns
+    Length of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_array_field{field}
+*/
+extern uint64_t bt_field_array_get_length(const bt_field *field);
+
+/*!
+@brief
+    Borrows the field at index \bt_p{index} from the \bt_array_field
+    \bt_p{field}.
 
+@attention
+    If \bt_p{field} is a dynamic array field, it must have a length
+    (call bt_field_array_dynamic_set_length()) before you call this
+    function.
+
+@param[in] field
+    Array field from which to borrow the field at index \bt_p{index}.
+@param[in] index
+    Index of the field to borrow from \bt_p{field}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the field of \bt_p{field} at index
+    \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{field} exists.
+    @endparblock
+
+@bt_pre_not_null{field}
+@bt_pre_is_array_field{field}
+@pre
+    \bt_p{index} is less than the length of \bt_p{field} (as returned by
+    bt_field_array_get_length()).
+
+@sa bt_field_array_borrow_element_field_by_index_const() &mdash;
+    \c const version of this function.
+*/
 extern bt_field *bt_field_array_borrow_element_field_by_index(
 		bt_field *field, uint64_t index);
 
+/*!
+@brief
+    Borrows the field at index \bt_p{index} from the \bt_array_field
+    \bt_p{field} (\c const version).
+
+See bt_field_array_borrow_element_field_by_index().
+*/
+extern const bt_field *
+bt_field_array_borrow_element_field_by_index_const(
+		const bt_field *field, uint64_t index);
+
+/*!
+@brief
+    Status codes for bt_field_array_dynamic_set_length().
+*/
 typedef enum bt_field_array_dynamic_set_length_status {
-	BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_MEMORY_ERROR	= __BT_FUNC_STATUS_MEMORY_ERROR,
+	/*!
+	@brief
+	    Success.
+	*/
 	BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_OK		= __BT_FUNC_STATUS_OK,
+
+	/*!
+	@brief
+	    Out of memory.
+	*/
+	BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_MEMORY_ERROR	= __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_field_array_dynamic_set_length_status;
 
+/*!
+@brief
+    Sets the length of the \bt_darray_field \bt_p{field}.
+
+@param[in] field
+    Dynamic array field of which to set the length.
+@param[in] length
+    New length of \bt_p{field}.
+
+@retval #BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_OK
+    Success.
+@retval #BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{field}
+@bt_pre_is_darray_field{field}
+@bt_pre_hot{field}
+*/
 extern bt_field_array_dynamic_set_length_status
-bt_field_array_dynamic_set_length(
-		bt_field *field, uint64_t length);
+bt_field_array_dynamic_set_length(bt_field *field, uint64_t length);
+
+/*! @} */
+
+/*!
+@name Structure field
+@{
+*/
+
+/*!
+@brief
+    Borrows the field of the member at index \bt_p{index} from the
+    \bt_struct_field \bt_p{field}.
+
+@param[in] field
+    Structure field from which to borrow the field of the member at
+    index \bt_p{index}.
+@param[in] index
+    Index of the member containing the field to borrow from
+    \bt_p{field}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the field of the member of \bt_p{field} at
+    index \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{field} exists.
+    @endparblock
+
+@bt_pre_not_null{field}
+@bt_pre_is_struct_field{field}
+@pre
+    \bt_p{index} is less than the number of members in the
+    \ref api-tir-fc-struct "class" of \bt_p{field} (as
+    returned by bt_field_class_structure_get_member_count()).
+
+@sa bt_field_structure_borrow_member_field_by_index_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_field *bt_field_structure_borrow_member_field_by_index(
+		bt_field *field, uint64_t index);
+
+/*!
+@brief
+    Borrows the field of the member at index \bt_p{index} from the
+    \bt_struct_field \bt_p{field} (\c const version).
+
+See bt_field_structure_borrow_member_field_by_index().
+*/
+extern const bt_field *
+bt_field_structure_borrow_member_field_by_index_const(
+		const bt_field *field, uint64_t index);
+
+/*!
+@brief
+    Borrows the field of the member having the name \bt_p{name} from the
+    \bt_struct_field \bt_p{field}.
+
+If there's no member having the name \bt_p{name} in the
+\ref api-tir-fc-struct "class" of \bt_p{field}, this function
+returns \c NULL.
+
+@param[in] field
+    Structure field from which to borrow the field of the member having
+    the name \bt_p{name}.
+@param[in] name
+    Name of the member containing the field to borrow from \bt_p{field}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the field of the member of \bt_p{field}
+    having the name \bt_p{name}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{field} exists.
+    @endparblock
+
+@bt_pre_not_null{field}
+@bt_pre_is_struct_field{field}
+@bt_pre_not_null{name}
+
+@sa bt_field_structure_borrow_member_field_by_name_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_field *bt_field_structure_borrow_member_field_by_name(
+		bt_field *field, const char *name);
+
+/*!
+@brief
+    Borrows the field of the member having the name \bt_p{name} from the
+    \bt_struct_field \bt_p{field} (\c const version).
+
+See bt_field_structure_borrow_member_field_by_name().
+*/
+extern const bt_field *
+bt_field_structure_borrow_member_field_by_name_const(
+		const bt_field *field, const char *name);
+
+/*! @} */
+
+/*!
+@name Option field
+@{
+*/
+
+/*!
+@brief
+    Sets whether or not the \bt_opt_field \bt_p{field}
+    has a field.
 
+@param[in] field
+    Option field of which to set whether or not it has a field.
+@param[in] has_field
+    #BT_TRUE to make \bt_p{field} have a field.
+
+@bt_pre_not_null{field}
+@bt_pre_is_opt_field{field}
+*/
 extern void bt_field_option_set_has_field(bt_field *field, bt_bool has_field);
 
+/*!
+@brief
+    Borrows the field of the \bt_opt_field \bt_p{field}.
+
+@attention
+    You must call bt_field_option_set_has_field() before you call
+    this function.
+
+If \bt_p{field} has no field, this function returns \c NULL.
+
+@param[in] field
+    Option field from which to borrow the field.
+
+@returns
+    @parblock
+    \em Borrowed reference of the field of \bt_p{field},
+    or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{field} exists.
+    @endparblock
+
+@bt_pre_not_null{field}
+@bt_pre_is_opt_field{field}
+
+@sa bt_field_option_set_has_field() &mdash;
+    Sets whether or not an option field has a field.
+@sa bt_field_option_borrow_field_const() &mdash;
+    \c const version of this function.
+*/
 extern bt_field *bt_field_option_borrow_field(bt_field *field);
 
+/*!
+@brief
+    Borrows the field of the \bt_opt_field \bt_p{field}
+    (\c const version).
+
+See bt_field_option_borrow_field().
+*/
+extern const bt_field *
+bt_field_option_borrow_field_const(const bt_field *field);
+
+/*! @} */
+
+/*!
+@name Variant field
+@{
+*/
+
+/*!
+@brief
+    Status code for bt_field_variant_select_option_by_index().
+*/
 typedef enum bt_field_variant_select_option_by_index_status {
-	BT_FIELD_VARIANT_SELECT_OPTION_STATUS_OK		= __BT_FUNC_STATUS_OK,
+	/*!
+	@brief
+	    Success.
+	*/
+	BT_FIELD_VARIANT_SELECT_OPTION_STATUS_OK	= __BT_FUNC_STATUS_OK,
 } bt_field_variant_select_option_by_index_status;
 
+/*!
+@brief
+    Sets the selected option of the \bt_var_field \bt_p{field}
+    to the option at index \bt_p{index}.
+
+@param[in] field
+    Variant field of which to set the selected option.
+@param[in] index
+    Index of the option to set as the selected option of \bt_p{field}.
+
+@retval #BT_FIELD_VARIANT_SELECT_OPTION_STATUS_OK
+    Success.
+
+@bt_pre_not_null{field}
+@bt_pre_is_var_field{field}
+@pre
+    \bt_p{index} is less than the number of options in the
+    \ref api-tir-fc-var "class" of \bt_p{field} (as
+    returned by bt_field_class_variant_get_option_count()).
+*/
 extern bt_field_variant_select_option_by_index_status
 bt_field_variant_select_option_by_index(
 		bt_field *field, uint64_t index);
 
+/*!
+@brief
+    Borrows the field of the selected option of the \bt_var_field
+    \bt_p{field}.
+
+@attention
+    You must call bt_field_variant_select_option_by_index() before
+    you call this function.
+
+@param[in] field
+    Variant field from which to borrow the selected option's field.
+
+@returns
+    @parblock
+    \em Borrowed reference of the field of the selected option of
+    \bt_p{field}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{field} exists.
+    @endparblock
+
+@bt_pre_not_null{field}
+@bt_pre_is_var_field{field}
+
+@sa bt_field_variant_select_option_by_index() &mdash;
+    Sets a variant field's selected option.
+@sa bt_field_variant_get_selected_option_index() &mdash;
+    Returns the index of a variant field's selected option.
+@sa bt_field_variant_borrow_selected_option_field_const() &mdash;
+    \c const version of this function.
+*/
 extern bt_field *bt_field_variant_borrow_selected_option_field(
 		bt_field *field);
 
+/*!
+@brief
+    Borrows the field of the selected option of the \bt_var_field
+    \bt_p{field} (\c const version).
+
+See bt_field_variant_borrow_selected_option_field().
+*/
+extern const bt_field *
+bt_field_variant_borrow_selected_option_field_const(
+		const bt_field *field);
+
+/*!
+@brief
+    Returns the index of the selected option of the \bt_var_field
+    \bt_p{field}.
+
+@param[in] field
+    Variant field of which to get the index of the selected option.
+
+@returns
+    Index of the selected option of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_var_field{field}
+
+@sa bt_field_variant_borrow_selected_option_field_const() &mdash;
+    Borrows the field of a variant field's selected option.
+*/
+extern uint64_t bt_field_variant_get_selected_option_index(
+		const bt_field *field);
+
+/*!
+@brief
+    Borrows the class of the selected option of the \bt_var_field
+    \bt_p{field}.
+
+This function returns
+
+@code
+bt_field_class_variant_borrow_option_by_index(
+    bt_field_variant_get_selected_option_index(field))
+@endcode
+
+@param[in] field
+    Variant field of which to get the selected option's class.
+
+@returns
+    Class of the selected option of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_var_field{field}
+*/
+extern const bt_field_class_variant_option *
+bt_field_variant_borrow_selected_option_class_const(
+		const bt_field *field);
+
+/*!
+@brief
+    Borrows the class of the selected option of the \bt_var_field
+    (with an unsigned integer selector field) \bt_p{field}.
+
+This function returns
+
+@code
+bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const(
+    bt_field_variant_get_selected_option_index(field))
+@endcode
+
+@param[in] field
+    Variant field of which to get the selected option's class.
+
+@returns
+    Class of the selected option of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_var_wuis_field{field}
+*/
+extern const bt_field_class_variant_with_selector_field_integer_unsigned_option *
+bt_field_variant_with_selector_field_integer_unsigned_borrow_selected_option_class_const(
+		const bt_field *field);
+
+/*!
+@brief
+    Borrows the class of the selected option of the \bt_var_field
+    (with a signed integer selector field) \bt_p{field}.
+
+This function returns
+
+@code
+bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const(
+    bt_field_variant_get_selected_option_index(field))
+@endcode
+
+@param[in] field
+    Variant field of which to get the selected option's class.
+
+@returns
+    Class of the selected option of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_var_wsis_field{field}
+*/
+extern const bt_field_class_variant_with_selector_field_integer_signed_option *
+bt_field_variant_with_selector_field_integer_signed_borrow_selected_option_class_const(
+		const bt_field *field);
+
+/*! @} */
+
+/*! @} */
+
 #ifdef __cplusplus
 }
 #endif