doc/api/dox: update pages

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

diff --git a/doc/api/dox/group-api-ref.dox b/doc/api/dox/group-api-ref.dox
index 745c534982e207df88f5427fcbaf004be1ad8217..23a838cb29424e5d03bfc518534c8a78d6b06f63 100644 (file)
--- a/doc/api/dox/group-api-ref.dox
+++ b/doc/api/dox/group-api-ref.dox
@@ -2,5 +2,29 @@
 @defgroup apiref API reference
 @brief Babeltrace C API reference.
 
-lol lol
+This module and its submodules accurately document the C API of the
+Babeltrace library (v\btversion). See the \ref writeplugin and
+\ref usectfwriter pages for official, procedural user guides to help
+you get started with this API. See \ref examples for informal examples.
+
+The API is divided into the following modules:
+
+- \ref refs contains the macros and functions that you can use
+  to manage the reference count of Babeltrace objects.
+- \ref values is a set of generic value objects which are used at
+  various locations of the API.
+- \ref ctfir is an internal representation of the
+  <a href="http://diamon.org/ctf/">CTF</a> model which Babeltrace
+  uses as a common foundation between trace formats.
+- \ref btcomponents is the Babeltrace component API. A component is an
+  instance of a specific component class within a trace conversion
+  graph of connected iterators.
+- \ref ctfwriter is an API to write concrete CTF traces to the
+  file system.
+
+All the functions and macros documented here indicate their
+\em preconditions and \em postconditions. Unless there is an
+unexpected error (out of memory, resource not available, bug, etc.),
+if you honor the preconditions when you call a function, you are
+guaranteed that this function in turn honors the postconditions.
 */

diff --git a/doc/api/dox/group-ctf-ir.dox b/doc/api/dox/group-ctf-ir.dox
index f8abd6e7b327a7bee05e35465c1f785965f55748..8c0dc6734903ce86ad3941e2e5c2999b49726f43 100644 (file)
--- a/doc/api/dox/group-ctf-ir.dox
+++ b/doc/api/dox/group-ctf-ir.dox
@@ -4,9 +4,16 @@
 @brief Common Trace Format Intermediate Representation.
 
 The <em>Common Trace Format Intermediate Representation</em>,
-or <strong><em>CTF IR</em></strong>, is a set of objects which are
-analogous to the model of the <a href="http://diamon.org/ctf">CTF</a>
-specification.
+or <strong><em>CTF IR</em></strong>, is the representation of the
+<a href="http://diamon.org/ctf">CTF</a> model within Babeltrace.
 
-TODO: add more stuff
+As with any Babeltrace object, all the CTF IR 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.
+
+When the documentation says that a given
+\link ctfirfieldtypes CTF IR field type\endlink must be
+<em>equivalent to</em> another one, it means that
+bt_ctf_field_type_compare() \em must return 0.
 */