Docs: add documentation for bt_ctf_field_type_enumeration_find_mappings*

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

diff --git a/doc/api/Doxyfile.in b/doc/api/Doxyfile.in
index 9adbac22798d2e5de6b3755945f48e2b41c71db1..7670a36fb6ca75c5c0a82e4173be1b299b18e7f2 100644 (file)
--- a/doc/api/Doxyfile.in
+++ b/doc/api/Doxyfile.in
@@ -49,6 +49,7 @@ ALIASES               += fts="\link ctfirfieldtypes CTF IR field types\endlink"
 ALIASES               += intft="\link ctfirintfieldtype CTF IR integer field type\endlink"
 ALIASES               += floatft="\link ctfirfloatfieldtype CTF IR floating point number field type\endlink"
 ALIASES               += enumft="\link ctfirenumfieldtype CTF IR enumeration field type\endlink"
+ALIASES               += enumiter="\link ctfirenummappingiter CTF IR enumeration mapping iterator\endlink"
 ALIASES               += stringft="\link ctfirstringfieldtype CTF IR string field type\endlink"
 ALIASES               += structft="\link ctfirstructfieldtype CTF IR structure field type\endlink"
 ALIASES               += arrayft="\link ctfirarrayfieldtype CTF IR array field type\endlink"

diff --git a/include/babeltrace/ctf-ir/field-types.h b/include/babeltrace/ctf-ir/field-types.h
index 420ae7f4faf07bbffb14b382b678b7e5b3c7d53b..05c21384c76ab0a2ed3a0dc489c8d535ae71ba4c 100644 (file)
--- a/include/babeltrace/ctf-ir/field-types.h
+++ b/include/babeltrace/ctf-ir/field-types.h
@@ -1177,34 +1177,19 @@ extern int bt_ctf_field_type_floating_point_set_mantissa_digits(
 
 /** @} */
 
-struct bt_ctf_field_type_enumeration_mapping_iterator *
-               bt_ctf_field_type_enumeration_find_mappings_by_name(
-                       struct bt_ctf_field_type *type,
-                       const char *name);
-
-struct bt_ctf_field_type_enumeration_mapping_iterator *
-               bt_ctf_field_type_enumeration_find_mappings_by_signed_value(
-                       struct bt_ctf_field_type *type,
-                       int64_t value);
-
-struct bt_ctf_field_type_enumeration_mapping_iterator *
-               bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(
-                       struct bt_ctf_field_type *type,
-                       uint64_t value);
-
-int bt_ctf_field_type_enumeration_mapping_iterator_get_name(
+extern int bt_ctf_field_type_enumeration_mapping_iterator_get_name(
                struct bt_ctf_field_type_enumeration_mapping_iterator *iter,
                const char **mapping_name);
 
-int bt_ctf_field_type_enumeration_mapping_iterator_get_signed(
+extern int bt_ctf_field_type_enumeration_mapping_iterator_get_signed(
                struct bt_ctf_field_type_enumeration_mapping_iterator *iter,
                const char **mapping_name, int64_t *lower, int64_t *upper);
 
-int bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(
+extern int bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(
                struct bt_ctf_field_type_enumeration_mapping_iterator *iter,
                const char **mapping_name, uint64_t *lower, uint64_t *upper);
 
-int bt_ctf_field_type_enumeration_mapping_iterator_next(
+extern int bt_ctf_field_type_enumeration_mapping_iterator_next(
                struct bt_ctf_field_type_enumeration_mapping_iterator *iter);
 
 /**
@@ -1261,6 +1246,7 @@ the \c CHERRY mapping.
 
 @sa ctfirenumfield
 @sa ctfirfieldtypes
+@sa ctfirenummappingiter
 
 @addtogroup ctfirenumfieldtype
 @{
@@ -1329,7 +1315,7 @@ On success, \p enum_field_type remains the sole owner of \p *name.
 
 @param[in] enum_field_type     Enumeration field type of which to get
                                the mapping at index \p index.
-­@param[in] index             Index of the mapping to get from
+@param[in] index               Index of the mapping to get from
                                \p enum_field_type.
 @param[out] name               Returned name of the mapping at index
                                \p index.
@@ -1371,7 +1357,7 @@ On success, \p enum_field_type remains the sole owner of \p *name.
 
 @param[in] enum_field_type     Enumeration field type of which to get
                                the mapping at index \p index.
-­@param[in] index             Index of the mapping to get from
+@param[in] index               Index of the mapping to get from
                                \p enum_field_type.
 @param[out] name               Returned name of the mapping at index
                                \p index.
@@ -1402,6 +1388,69 @@ extern int bt_ctf_field_type_enumeration_get_mapping_unsigned(
                const char **name, uint64_t *range_begin,
                uint64_t *range_end);
 
+/**
+@brief  Returns a @enumiter on the mappings of the @enumft
+       \p enum_field_type that match \p name.
+
+@param[in] enum_field_type     Enumeration field type of which to get
+                               the mapping at index \p index.
+@param[in] name                        Name of the mappings to find.
+@returns                       @enumiter that
+                               match \p name, or \c NULL on error.
+
+@prenotnull{enum_field_type}
+@prenotnull{name}
+@preisenumft{enum_field_type}
+@postrefcountsame{enum_field_type}
+@postsuccessrefcountret1
+*/
+extern struct bt_ctf_field_type_enumeration_mapping_iterator *
+bt_ctf_field_type_enumeration_find_mappings_by_name(
+               struct bt_ctf_field_type *enum_field_type,
+               const char *name);
+
+/**
+@brief  Returns the mappings of the @enumft
+       \p enum_field_type that match \p value.
+
+@param[in] enum_field_type     Enumeration field type of which to get
+                               the mapping at index \p index.
+@param[in] value               Signed value of the mappings to find.
+@returns                       Iterator on enumeration mappings that
+                               match \p value, or \c NULL on error.
+
+@prenotnull{enum_field_type}
+@prenotnull{name}
+@preisenumft{enum_field_type}
+@postrefcountsame{enum_field_type}
+@postsuccessrefcountret1
+*/
+extern struct bt_ctf_field_type_enumeration_mapping_iterator *
+bt_ctf_field_type_enumeration_find_mappings_by_signed_value(
+               struct bt_ctf_field_type *enum_field_type,
+               int64_t value);
+
+/**
+@brief  Returns the mappings of the @enumft
+       \p enum_field_type that match \p value.
+
+@param[in] enum_field_type     Enumeration field type of which to get
+                               the mapping at index \p index.
+@param[in] value               Unsigned value of the mappings to find.
+@returns                       Iterator on enumeration mappings that
+                               match \p value, or \c NULL on error.
+
+@prenotnull{enum_field_type}
+@prenotnull{name}
+@preisenumft{enum_field_type}
+@postrefcountsame{enum_field_type}
+@postsuccessrefcountret1
+*/
+extern struct bt_ctf_field_type_enumeration_mapping_iterator *
+bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(
+               struct bt_ctf_field_type *enum_field_type,
+               uint64_t value);
+
 /**
 @brief  Adds a mapping to the @enumft \p enum_field_type which maps the
        name \p name to the signed range \p range_begin (included) to

diff --git a/include/babeltrace/ctf-ir/fields.h b/include/babeltrace/ctf-ir/fields.h
index 4cc8b03d8df55fddc6bd18b6d51b10ec0e469bf7..3a4c76a66dc6b30286f20942d81319bbe81b1076 100644 (file)
--- a/include/babeltrace/ctf-ir/fields.h
+++ b/include/babeltrace/ctf-ir/fields.h
@@ -639,12 +639,9 @@ extern struct bt_ctf_field *bt_ctf_field_enumeration_get_container(
                struct bt_ctf_field *enum_field);
 
 /**
-@brief Returns an iterator to the mappings selected by the current
+@brief Returns a @enumiter to the mappings selected by the current
        integral value of the @enumfield \p enum_field.
 
-On success, \p enum_field remains the sole owner of the returned
-value.
-
 @param[in] enum_field  Enumeration field of which to get the name of
                        mapping associated to its current integral
                        value.
@@ -657,6 +654,7 @@ value.
 @pre The wrapped integer field of \p enum_field contains an integral
        value.
 @postrefcountsame{enum_field}
+@postsuccessrefcountret1
 */
 extern struct bt_ctf_field_type_enumeration_mapping_iterator *
 bt_ctf_field_enumeration_get_mappings(struct bt_ctf_field *enum_field);