Document stream.h (API)

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 3c25917643be60323d299a4c6d8d3cfc6fabe546..9b8c1edc8fff3003e102d6048cae2c407db89a75 100644 (file)
--- a/doc/api/Doxyfile.in
+++ b/doc/api/Doxyfile.in
@@ -25,6 +25,7 @@ ALIASES               += postsuccessrefcountretinc="@post <strong>On success</st
 ALIASES               += postsuccessrefcountret1="@post <strong>On success</strong>, the reference count of the returned object is 1."
 ALIASES               += postsuccessrefcountinc{1}="@post <strong>On success</strong>, the reference count of \p \1 is incremented."
 ALIASES               += postrefcountsame{1}="@post The reference count of \p \1 is not modified."
+ALIASES               += postsuccessfrozen{1}="@post <strong>On success</strong>, \p \1 is frozen."
 ALIASES               += prenotnull{1}="@pre \p \1 is not \c NULL."
 ALIASES               += prehot{1}="@pre \p \1 is not frozen."
 ALIASES               += preisintft{1}="@pre \p \1 is a CTF IR integer field type."
@@ -44,6 +45,7 @@ ALIASES               += preisarrayfield{1}="@pre \p \1 is a CTF IR array field.
 ALIASES               += preisseqfield{1}="@pre \p \1 is a CTF IR sequence field."
 ALIASES               += preisvarfield{1}="@pre \p \1 is a CTF IR variant field."
 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.\""
 OPTIMIZE_OUTPUT_FOR_C  = YES
 MARKDOWN_SUPPORT       = YES
 TOC_INCLUDE_HEADINGS   = 0

diff --git a/doc/api/images/ctf-trace.png b/doc/api/images/ctf-trace.png
new file mode 100644 (file)
index 0000000..64a389c
Binary files /dev/null and b/doc/api/images/ctf-trace.png differ

diff --git a/include/babeltrace/ctf-ir/stream.h b/include/babeltrace/ctf-ir/stream.h
index a08e327f5d38de1a28c223796c9aef7366d094e3..8de7e24378ec3e158db027419926c41382981f2f 100644 (file)
--- a/include/babeltrace/ctf-ir/stream.h
+++ b/include/babeltrace/ctf-ir/stream.h
@@ -37,25 +37,121 @@
 extern "C" {
 #endif
 
-struct bt_ctf_event;
+/**
+@defgroup ctfirstream CTF IR stream
+@ingroup ctfir
+@brief CTF IR stream.
+
+@note
+See \ref ctfirwriterstream which documents additional CTF IR stream
+functions exclusive to the CTF IR writer mode.
+
+A CTF IR <strong><em>stream</em></strong> is an instance of a
+\link ctfirstreamclass CTF IR stream class\endlink.
+
+You can obtain a CTF IR stream object in two different modes:
+
+- <strong>Normal mode</strong>: use bt_ctf_stream_create() with a stream
+  class having a \link ctfirtraceclass CTF IR trace class\endlink parent
+  \em not created by a \link ctfirwriter CTF IR writer\endlink object to
+  create a default stream.
+- <strong>CTF IR writer mode</strong>: use bt_ctf_stream_create() with
+  a stream class having a trace class parent created by a CTF IR writer
+  object, or use bt_ctf_writer_create_stream().
+
+A CTF IR stream object represents a CTF stream, that is, a sequence of
+packets containing events:
+
+@imgtracestructure
+
+A CTF IR stream does not contain, however, actual \link ctfirpacket CTF
+IR packet\endlink objects: it only acts as a common parent to identify
+the original CTF stream of packet objects.
+
+As with any Babeltrace object, CTF IR stream objects have
+<a href="https://en.wikipedia.org/wiki/Reference_counting">reference
+counts</a>. See \ref refs to learn more about the reference counting
+management of Babeltrace objects.
+
+@sa ctfirstreamclass
+@sa ctfirpacket
+@sa ctfirwriterstream
+
+@file
+@brief CTF IR stream type and functions.
+@sa ctfirstream
+
+@addtogroup ctfirstream
+@{
+*/
+
 struct bt_ctf_stream;
+struct bt_ctf_event;
+
+/**
+@brief  Creates a default CTF IR stream named \p name from the CTF IR
+       stream class \p stream_class.
 
+\p stream_class \em must have a parent
+\link ctfirtraceclass CTF IR trace class\endlink.
+
+If the parent \link ctfirtraceclass trace class\endlink of
+\p stream_class was created by a \link ctfirwriter CTF IR writer\endlink
+object, then the stream object is created in CTF IR writer mode, and
+you can use the functions of \ref ctfirwriterstream on it.
+Otherwise it is created in normal mode: you should only use the
+functions documented in this module on it.
+
+\p name can be \c NULL to create an unnamed stream object.
+
+@param[in] stream_class        CTF IR stream class to use to create the
+                       CTF IR stream.
+@param[in] name                Name of the stream object to create (copied on
+                       success) or \c NULL to create an unnamed stream.
+@returns               Created stream object, or \c NULL on error.
+
+@prenotnull{stream_class}
+@pre \p stream_class has a parent trace class.
+@postsuccessrefcountret1
+*/
 extern struct bt_ctf_stream *bt_ctf_stream_create(
                struct bt_ctf_stream_class *stream_class,
                const char *name);
 
+/**
+@brief Returns the name of the CTF IR stream \p stream.
+
+On success, \p stream remains the sole owner of the returned string.
+
+@param[in] stream      Stream object of which to get the name.
+@returns               Name of stream \p stream, or \c NULL if
+                       \p stream is unnamed or on error.
+
+@prenotnull{stream}
+@postrefcountsame{stream}
+*/
 extern const char *bt_ctf_stream_get_name(struct bt_ctf_stream *stream);
 
-/*
- * bt_ctf_stream_get_stream_class: get a stream's class.
- *
- * @param stream Stream instance.
- *
- * Returns the stream's class, NULL on error.
- */
+/**
+@brief Returns the parent CTF IR stream class of the CTF IR
+       stream \p stream.
+
+This function returns a reference to the stream class which was used
+to create the stream object in the first place with
+bt_ctf_stream_create().
+
+@param[in] stream      Stream of which to get the parent stream class.
+@returns               Parent stream class of \p stream,
+                       or \c NULL on error.
+
+@prenotnull{stream}
+@postsuccessrefcountretinc
+*/
 extern struct bt_ctf_stream_class *bt_ctf_stream_get_class(
                struct bt_ctf_stream *stream);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif