API doc: add notes about automatic resolving

[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 850f4b7df6396d26ed0c9df2d157d3685c12fb9f..fecab1547cd349fa928006710b68461260146479 100644 (file)
--- a/include/babeltrace/ctf-ir/event.h
+++ b/include/babeltrace/ctf-ir/event.h
@@ -141,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.
@@ -209,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}