API doc: add int/float field type examples

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

diff --git a/doc/api/Doxyfile.in b/doc/api/Doxyfile.in
index 8be69c56385d2361a4d2cf7136b3ff95a22df18d..9adbac22798d2e5de6b3755945f48e2b41c71db1 100644 (file)
--- a/doc/api/Doxyfile.in
+++ b/doc/api/Doxyfile.in
@@ -82,6 +82,7 @@ ALIASES               += seqfields="\link ctfirseqfield CTF IR sequence fields\e
 ALIASES               += varfields="\link ctfirvarfield CTF IR variant fields\endlink"
 ALIASES               += imgpacketstructure="@image html ctf-stream-packet.png \"Structure of a CTF packet.\""
 ALIASES               += imgtracestructure="@image html ctf-trace.png \"Structure of a CTF trace.\""
+ALIASES               += noteexamplesassert="@note In the following examples, we use \c assert() to validate the results of the called functions."
 OPTIMIZE_OUTPUT_FOR_C  = YES
 MARKDOWN_SUPPORT       = YES
 TOC_INCLUDE_HEADINGS   = 0
@@ -148,6 +149,7 @@ INPUT                  = "@top_srcdir@/include/babeltrace/ctf-ir" \
                          "@srcdir@/dox/write-plugin.dox" \
                          "@srcdir@/dox/use-ctf-writer.dox" \
                          "@srcdir@/dox/examples.dox" \
+                         "@srcdir@/dox/examples-ctfir.dox" \
                          "@srcdir@/dox/group-api-ref.dox" \
                          "@srcdir@/dox/group-ctf-ir.dox"
 INPUT_ENCODING         = UTF-8

diff --git a/doc/api/dox/examples-ctfir.dox b/doc/api/dox/examples-ctfir.dox
new file mode 100644 (file)
index 0000000..1dc632f
--- /dev/null
+++ b/doc/api/dox/examples-ctfir.dox
@@ -0,0 +1,139 @@
+/**
+@page ctfirexamples CTF IR examples
+
+<strong>List of CTF IR examples</strong>:
+
+- @subpage ctfirfieldtypesexamples CTF IR field types examples
+
+@sa ctfir (API reference)
+
+
+@page ctfirfieldtypesexamples CTF IR field types examples
+
+This page contains usage examples of the \ref ctfirfieldtypes API.
+
+@noteexamplesassert
+
+
+@section ctfirfieldtypesexamples_intfieldtype Integer field type
+
+@sa ctfirintfieldtype
+
+@subsection ctfirfieldtypesexamples_intfieldtype0 Create a default, 16-bit integer field type
+
+@code{.c}
+#include <assert.h>
+#include <babeltrace/ctf-ir/field-types.h>
+
+struct bt_ctf_field_type *create_int_field_type(void)
+{
+    struct bt_ctf_field_type *field_type;
+
+    field_type = bt_ctf_field_type_integer_create(16);
+    assert(field_type);
+
+    return field_type;
+}
+@endcode
+
+@subsection ctfirfieldtypesexamples_intfieldtype1 Create a 23-bit, signed, big-endian integer field type
+
+@code{.c}
+#include <assert.h>
+#include <babeltrace/ctf-ir/field-types.h>
+
+struct bt_ctf_field_type *create_int_field_type(void)
+{
+    int ret;
+    struct bt_ctf_field_type *field_type;
+
+    field_type = bt_ctf_field_type_integer_create(23);
+    assert(field_type);
+
+    ret = bt_ctf_field_type_set_byte_order(field_type,
+                                           BT_CTF_BYTE_ORDER_BIG_ENDIAN);
+    assert(ret == 0);
+
+    ret = bt_ctf_field_type_integer_set_signed(field_type, 1);
+    assert(ret == 0);
+
+    return field_type;
+}
+@endcode
+
+@subsection ctfirfieldtypesexamples_intfieldtype2 Create an 8-bit integer field type, displayed in hexadecimal, mapped to a CTF IR clock class
+
+@code{.c}
+#include <assert.h>
+#include <babeltrace/ctf-ir/field-types.h>
+
+struct bt_ctf_field_type *create_int_field_type(
+        struct bt_ctf_clock_class *clock_class)
+{
+    int ret;
+    struct bt_ctf_field_type *field_type;
+
+    field_type = bt_ctf_field_type_integer_create(8);
+    assert(field_type);
+
+    ret = bt_ctf_field_type_integer_set_base(field_type,
+                                             BT_CTF_INTEGER_BASE_HEXADECIMAL);
+    assert(ret == 0);
+
+    ret = bt_ctf_field_type_integer_set_mapped_clock(field_type, clock_class);
+    assert(ret == 0);
+
+    return field_type;
+}
+@endcode
+
+
+@section ctfirfieldtypesexamples_floatfieldtype Floating point number field type
+
+@sa ctfirfloatfieldtype
+
+@subsection ctfirfieldtypesexamples_floatfieldtype0 Create a default floating point number field type
+
+@code{.c}
+#include <assert.h>
+#include <babeltrace/ctf-ir/field-types.h>
+
+struct bt_ctf_field_type *create_float_field_type(void)
+{
+    struct bt_ctf_field_type *field_type;
+
+    field_type = bt_ctf_field_type_floating_point_create();
+    assert(field_type);
+
+    return field_type;
+}
+@endcode
+
+@subsection ctfirfieldtypesexamples_floatfieldtype1 Create a "double", little-endian floating point number field type
+
+@code{.c}
+#include <assert.h>
+#include <babeltrace/ctf-ir/field-types.h>
+
+struct bt_ctf_field_type *create_float_field_type(void)
+{
+    int ret;
+    struct bt_ctf_field_type *field_type;
+
+    field_type = bt_ctf_field_type_floating_point_create();
+    assert(field_type);
+
+    ret = bt_ctf_field_type_set_byte_order(field_type,
+                                           BT_CTF_BYTE_ORDER_LITTLE_ENDIAN);
+    assert(ret == 0);
+
+    ret = bt_ctf_field_type_floating_point_set_exponent_digits(field_type, 11);
+    assert(ret == 0);
+
+    ret = bt_ctf_field_type_floating_point_set_mantissa_digits(field_type, 53);
+    assert(ret == 0);
+
+    return field_type;
+}
+@endcode
+*/

diff --git a/doc/api/dox/examples.dox b/doc/api/dox/examples.dox
new file mode 100644 (file)
index 0000000..34691ad
--- /dev/null
+++ b/doc/api/dox/examples.dox
@@ -0,0 +1,7 @@
+/**
+@page examples Examples
+
+<strong>List of examples</strong>:
+
+- @subpage ctfirexamples CTF IR examples
+*/

diff --git a/doc/api/dox/group-ctf-ir.dox b/doc/api/dox/group-ctf-ir.dox
index 8c0dc6734903ce86ad3941e2e5c2999b49726f43..4052b3d9ef4a13b2608929ca585fe13724e120b9 100644 (file)
--- a/doc/api/dox/group-ctf-ir.dox
+++ b/doc/api/dox/group-ctf-ir.dox
@@ -16,4 +16,6 @@ When the documentation says that a given
 \link ctfirfieldtypes CTF IR field type\endlink must be
 <em>equivalent to</em> another one, it means that
 bt_ctf_field_type_compare() \em must return 0.
+
+@sa \ref ctfirexamples "Examples"
 */

diff --git a/include/babeltrace/ctf-ir/field-types.h b/include/babeltrace/ctf-ir/field-types.h
index b9896e3d7c3dd23175a395f34f4fa49ec4a03d0c..682d1a1e03c99fdb72acdd59e5e7e62d4dfc7819 100644 (file)
--- a/include/babeltrace/ctf-ir/field-types.h
+++ b/include/babeltrace/ctf-ir/field-types.h
@@ -178,6 +178,7 @@ You cannot modify a frozen field type object: it is considered
 immutable, except for \link refs reference counting\endlink.
 
 @sa ctfirfields
+@sa \ref ctfirfieldtypesexamples "Examples"
 
 @file
 @brief CTF IR field types type and functions.
@@ -732,6 +733,7 @@ An integer field type has the following properties:
 
 @sa ctfirintfield
 @sa ctfirfieldtypes
+@sa \ref ctfirfieldtypesexamples_intfieldtype "Examples"
 
 @addtogroup ctfirintfieldtype
 @{
@@ -1046,6 +1048,7 @@ A floating point number field type has the following properties:
 
 @sa ctfirfloatfield
 @sa ctfirfieldtypes
+@sa \ref ctfirfieldtypesexamples_floatfieldtype "Examples"
 
 @addtogroup ctfirfloatfieldtype
 @{