Document field-path.h (API)

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

diff --git a/include/babeltrace/ctf-ir/field-path.h b/include/babeltrace/ctf-ir/field-path.h
index 40acfc8b3e56d633c5cded9c60a74109cc376bf8..7b009828c547e0e22946783667f79f19ea31bf39 100644 (file)
--- a/include/babeltrace/ctf-ir/field-path.h
+++ b/include/babeltrace/ctf-ir/field-path.h
@@ -34,46 +34,106 @@
 extern "C" {
 #endif
 
+/**
+@defgroup ctfirfieldpath CTF IR field path
+@ingroup ctfir
+@brief CTF IR field path.
+
+@code
+#include <babeltrace/ctf-ir/field-path.h>
+@endcode
+
+A CTF IR <strong><em>field path</em></strong> represents an absolute
+path to a field in the hierarchy of a
+\link ctfirtraceclass CTF IR trace class\endlink, of a
+\link ctfirstreamclass CTF IR stream class\endlink, or of a
+\link ctfireventclass CTF IR event class\endlink.
+
+As a reminder, here's the structure of a CTF packet:
+
+@imgpacketstructure
+
+Sequence and variant \link ctfirfieldtypes CTF IR field types\endlink
+can return a field path to resp. their length field and tag field
+with resp. bt_ctf_field_type_sequence_get_length_field_path() and
+bt_ctf_field_type_variant_get_tag_field_path().
+
+A field path has a <em>root scope</em> which indicates from which of the
+six CTF scopes to begin. It also has a list of structure field <em>path
+indexes</em> which indicate the path to take to reach the destination
+field. A path index set to -1 means that you need to continue the lookup
+within the current element of an array or sequence field.
+
+As with any Babeltrace object, CTF IR field path objects have
+<a href="https://en.wikipedia.org/wiki/Reference_counting">reference
+counts</a>. See \ref refs to learn more about the reference counting
+management of Babeltrace objects.
+
+@file
+@brief CTF IR field path type and functions.
+@sa ctfirfieldpath
+
+@addtogroup ctfirfieldpath
+@{
+*/
+
+/**
+@struct bt_ctf_field_path
+@brief A CTF IR field path.
+@sa ctfirfieldpath
+*/
 struct bt_ctf_field_path;
 
-/*
- * bt_ctf_field_path_get_root_scope: get the root node of a field path.
- *
- * Get the field path's root node.
- *
- * @param field_path Field path.
- *
- * Returns the root node of a field path, or BT_CTF_SCOPE_UNKNOWN on error.
- */
+/**
+@brief Returns the root scope of the CTF IR field path \p field_path.
+
+@param[in] field_path  Field path of which to get the root scope.
+@returns               Root scope of \p field_path, or
+                       #BT_CTF_SCOPE_UNKNOWN on error.
+
+@prenotnull{field_path}
+@postrefcountsame{field_path}
+*/
 extern enum bt_ctf_scope bt_ctf_field_path_get_root_scope(
                const struct bt_ctf_field_path *field_path);
 
-/*
- * bt_ctf_field_path_get_index_count: get the number of indexes of a field path.
- *
- * Get the number of indexes of a field path.
- *
- * @param field_path Field path.
- *
- * Returns the field path's index count, or a negative value on error.
- */
+/**
+@brief Returns the number of path indexes contained in the CTF IR field
+       path \p field_path.
+
+@param[in] field_path  Field path of which to get the number of
+                       path indexes.
+@returns               Number of path indexes contained in
+                       \p field_path, or a negative value on error.
+
+@prenotnull{field_path}
+@postrefcountsame{field_path}
+*/
 extern int bt_ctf_field_path_get_index_count(
                const struct bt_ctf_field_path *field_path);
 
-/*
- * bt_ctf_field_path_get_index: get the field path's index at a specific index.
- *
- * Get the field path's index at a specific index.
- *
- * @param field_path Field path.
- * @param index Index.
- *
- * Returns a field path index, or INT_MIN on error.
- */
+/**
+@brief Returns the path index contained in the CTF IR field
+       path \p field_path at index \p index.
+
+@param[in] field_path  Field path of which to get the path index
+                       at index \p index.
+@param[in] index       Index of path index to get.
+@returns               Path index of \p field_path at index \p index,
+                       or \c INT_MIN on error.
+
+@prenotnull{field_path}
+@pre \p index is lesser than the number of path indexes contained in the
+       field path \p field_path (see
+       bt_ctf_field_path_get_index_count()).
+@postrefcountsame{field_path}
+*/
 extern int bt_ctf_field_path_get_index(
                const struct bt_ctf_field_path *field_path,
                int index);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif