From bb8c17e07565208e2a397b2f02057d6453f39843 Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Fri, 2 Dec 2016 21:45:37 -0500 Subject: [PATCH] API doc: add int/float field type examples MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Philippe Proulx Signed-off-by: Jérémie Galarneau --- doc/api/Doxyfile.in | 2 + doc/api/dox/examples-ctfir.dox | 139 ++++++++++++++++++++++++ doc/api/dox/examples.dox | 7 ++ doc/api/dox/group-ctf-ir.dox | 2 + include/babeltrace/ctf-ir/field-types.h | 3 + 5 files changed, 153 insertions(+) create mode 100644 doc/api/dox/examples-ctfir.dox create mode 100644 doc/api/dox/examples.dox diff --git a/doc/api/Doxyfile.in b/doc/api/Doxyfile.in index 8be69c56..9adbac22 100644 --- 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 index 00000000..1dc632f7 --- /dev/null +++ b/doc/api/dox/examples-ctfir.dox @@ -0,0 +1,139 @@ +/** +@page ctfirexamples CTF IR examples + +List of CTF IR examples: + +- @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 +#include + +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 +#include + +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 +#include + +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 +#include + +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 +#include + +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 index 00000000..34691ad4 --- /dev/null +++ b/doc/api/dox/examples.dox @@ -0,0 +1,7 @@ +/** +@page examples Examples + +List of examples: + +- @subpage ctfirexamples CTF IR examples +*/ diff --git a/doc/api/dox/group-ctf-ir.dox b/doc/api/dox/group-ctf-ir.dox index 8c0dc673..4052b3d9 100644 --- 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 equivalent to 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 b9896e3d..682d1a1e 100644 --- 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 @{ -- 2.34.1