event.h: doc: put @cond/@endcond on single lines

[babeltrace.git] / include / babeltrace / ctf-ir / event.h

diff --git a/include/babeltrace/ctf-ir/event.h b/include/babeltrace/ctf-ir/event.h
index 54b284c4014786a313b89b5a877345633505b7ff..64cd68f27bc20aa4aaeeea96885f4aba102798de 100644 (file)
--- a/include/babeltrace/ctf-ir/event.h
+++ b/include/babeltrace/ctf-ir/event.h
@@ -43,6 +43,10 @@ extern "C" {
 @ingroup ctfir
 @brief CTF IR event.
 
+@code
+#include <babeltrace/ctf-ir/event.h>
+@endcode
+
 A CTF IR <strong><em>event</em></strong> is a container of event
 fields:
 
@@ -137,6 +141,17 @@ can set them with bt_ctf_event_set_header(),
 bt_ctf_event_set_stream_event_context(),
 bt_ctf_event_set_event_context(), and bt_ctf_event_set_payload_field().
 
+This function tries to resolve the needed
+\link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
+types that are found anywhere in the context or payload field
+types of \p event_class and in the root field types of the
+parent stream class of \p event_class. If any automatic resolving fails,
+this function fails. This means that, if any dynamic field type need
+a field type which should be found in the trace packet header root
+field type, and if the parent stream class of \p event_class was not
+added to a \link ctfirtraceclass CTF IR trace class\endlink yet
+with bt_ctf_trace_add_stream_class(), then this function fails.
+
 @param[in] event_class CTF IR event class to use to create the
                        CTF IR event.
 @returns               Created event object, or \c NULL on error.
@@ -160,6 +175,7 @@ create the event object in the first place with bt_ctf_event_create().
                        or \c NULL on error.
 
 @prenotnull{event}
+@postrefcountsame{event}
 @postsuccessrefcountretinc
 */
 extern struct bt_ctf_event_class *bt_ctf_event_get_class(
@@ -178,6 +194,7 @@ This function returns a reference to the event class which was set to
                        \p event or on error.
 
 @prenotnull{event}
+@postrefcountsame{event}
 @postsuccessrefcountretinc
 
 @sa bt_ctf_event_set_packet(): Associates a given event to a given
@@ -203,6 +220,7 @@ On success, this function also sets the parent stream object of
 \p event to the parent stream of \p packet.
 
 @param[in] event       Event to which to associate \p packet.
+@param[in] packet      Packet to associate to \p event.
 @returns               0 on success, or a negative value on error.
 
 @prenotnull{event}
@@ -226,6 +244,7 @@ extern int bt_ctf_event_set_packet(struct bt_ctf_event *event,
 @returns               Parent stream of \p event, or \c NULL on error.
 
 @prenotnull{event}
+@postrefcountsame{event}
 @postsuccessrefcountretinc
 */
 extern struct bt_ctf_stream *bt_ctf_event_get_stream(
@@ -249,6 +268,7 @@ extern struct bt_ctf_stream *bt_ctf_event_get_stream(
                        field is not set or on error.
 
 @prenotnull{event}
+@postrefcountsame{event}
 @postsuccessrefcountretinc
 
 @sa bt_ctf_event_get_header(): Sets the stream event header
@@ -297,6 +317,7 @@ extern int bt_ctf_event_set_header(struct bt_ctf_event *event,
                        field is not set or on error.
 
 @prenotnull{event}
+@postrefcountsame{event}
 @postsuccessrefcountretinc
 
 @sa bt_ctf_event_set_stream_event_context(): Sets the stream event
@@ -344,6 +365,7 @@ extern int bt_ctf_event_set_stream_event_context(struct bt_ctf_event *event,
                        the event context field is not set or on error.
 
 @prenotnull{event}
+@postrefcountsame{event}
 @postsuccessrefcountretinc
 
 @sa bt_ctf_event_set_event_context(): Sets the event context field of a
@@ -390,6 +412,7 @@ extern int bt_ctf_event_set_event_context(struct bt_ctf_event *event,
                        the event payload field is not set or on error.
 
 @prenotnull{event}
+@postrefcountsame{event}
 @postsuccessrefcountretinc
 
 @sa bt_ctf_event_set_payload_field(): Sets the event payload field of a
@@ -426,9 +449,7 @@ of \p event.
 extern int bt_ctf_event_set_payload_field(struct bt_ctf_event *event,
                struct bt_ctf_field *payload);
 
-/**
-@cond DOCUMENT
-*/
+/** @cond DOCUMENT */
 
 /*
  * TODO: Doxygenize.
@@ -492,9 +513,7 @@ extern int bt_ctf_event_set_payload(struct bt_ctf_event *event,
                const char *name,
                struct bt_ctf_field *value);
 
-/**
-@endcond
-*/
+/** @endcond */
 
 /** @} */