From: Philippe Proulx <eeppeliteloop@gmail.com>
Date: Wed, 23 Nov 2016 05:53:17 +0000 (-0500)
Subject: Document field-path.h (API)
X-Git-Tag: v2.0.0-pre1~664
X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=commitdiff_plain;h=269b496c1560c8dde32cb312d20d75796063998a

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 40acfc8b..7b009828 100644
--- 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