From: Philippe Proulx <eeppeliteloop@gmail.com>
Date: Wed, 23 Nov 2016 06:44:41 +0000 (-0500)
Subject: API doc: add notes about automatic resolving
X-Git-Tag: v2.0.0-pre1~663
X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=commitdiff_plain;h=4cdafd515891b2541a078030c4cfc1a17c6f2315

API doc: add notes about automatic resolving

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

diff --git a/include/babeltrace/ctf-ir/event.h b/include/babeltrace/ctf-ir/event.h
index dc433921..fecab154 100644
--- 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.
diff --git a/include/babeltrace/ctf-ir/stream-class.h b/include/babeltrace/ctf-ir/stream-class.h
index 40dbf819..d2b16ded 100644
--- a/include/babeltrace/ctf-ir/stream-class.h
+++ b/include/babeltrace/ctf-ir/stream-class.h
@@ -526,6 +526,20 @@ You can call this function even if \p stream_class is frozen. Adding
 event classes is the only operation that is permitted
 on a frozen stream class.
 
+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. If any automatic resolving fails:
+
+- If the needed field type should be found in one of the root field
+  types of \p event_class or \p stream_class, this function fails.
+- If \p stream_class is the child of a
+  \link ctfirtraceclass CTF IR trace class\endlink (it was added
+  with bt_ctf_trace_add_stream_class()), this function fails.
+- If \p stream_class is not the child of a trace class yet, the
+  automatic resolving is reported to the next call to
+  bt_ctf_trace_add_stream_class() with \p stream_class.
+
 @param[in] stream_class	Stream class to which to add \p event_class.
 @param[in] event_class	Event class to add to \p stream_class.
 @returns		0 on success, or a negative value on error.
diff --git a/include/babeltrace/ctf-ir/trace.h b/include/babeltrace/ctf-ir/trace.h
index 93878ebc..840ebf37 100644
--- a/include/babeltrace/ctf-ir/trace.h
+++ b/include/babeltrace/ctf-ir/trace.h
@@ -680,6 +680,13 @@ You can only add a given stream class to one trace class.
 
 You can call this function even if \p trace_class is frozen.
 
+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 root field types of
+\p stream_class and of all its currently contained
+\link ctfireventclass CTF IR event classes\endlink. If any automatic
+resolving fails, then this function fails.
+
 @param[in] trace_class	Trace class to which to add \p stream_class.
 @param[in] stream_class	Stream class to add to \p trace_class.
 @returns		0 on success, or a negative value on error.