From: Philippe Proulx <eeppeliteloop@gmail.com>
Date: Sat, 26 Nov 2016 02:24:16 +0000 (-0500)
Subject: doc/api/dox: update pages
X-Git-Tag: v2.0.0-pre1~642
X-Git-Url: https://git.efficios.com/?p=babeltrace.git;a=commitdiff_plain;h=3db22dc042ba44704369b3a09bddb68ffa4aa6e9

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 745c5349..23a838cb 100644
--- 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 f8abd6e7..8c0dc673 100644
--- 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.
 */