Fix: Documentation cleanup

Add high-level information about declarations, definitions and scopes in
the API documentation.
Add some missing API function documentation in the API doc.
Clarify the usage of the declaration listing functions.

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>

diff --git a/doc/API.txt b/doc/API.txt
index bc3a4a10512e1aef477ee950de8a61d009250159..e13e6adf3545d306e36c2496dd2feb50479d1eea 100644 (file)
--- a/doc/API.txt
+++ b/doc/API.txt
@@ -28,6 +28,20 @@ TERMINOLOGY
 * A "trace handle" is a unique identifier representing a trace file.
   It allows the user to manipulate a trace directly.
 
+* The "declaration" of a field or an event, is the structure which contains
+  the representaion of an object as declared in the metadata. All the
+  declarations of all events and fields can be accessed as soon as the trace is
+  open, but of course they contain no trace data, just the layout.
+
+* The "definition" of a field or an event is the structure in which the actual
+  trace data is contained. When we read an event in the trace, we access its
+  definition and we can access all the field definitions contained in all the
+  scopes of this event to the get the actual data.
+
+* "Scopes" allow specifying the level at which the information about the
+  current event must be fetched: event header, event payload, event context,
+  stream context. Compound-type (arrays, structures, sequences and variants)
+  fields are relative scopes which contain fields.
 
 
 USAGE
@@ -125,8 +139,13 @@ variant)
 
 For more information on each scope, see the CTF specifications.
 
-The function to get a field list is the bt_ctf_get_field_list(). The function
-to get the definition of a specific field is bt_ctf_get_field().
+The bt_ctf_get_field_list() function gives access to the list of fields in the
+current event. The bt_ctf_get_field() function gives acces to of a specific
+field of an event.
+
+The bt_ctf_get_event_decl_list() and bt_ctf_get_decl_fields() functions give
+respectively access to the list of the events declared in a trace and the list
+of the fields declared in an event.
 
 Once the field is obtained, we can obtain its name and type using the
 bt_ctf_field_name() and bt_ctf_field_type() functions respectively. The
@@ -143,8 +162,8 @@ possible types are defined in the ctf_type_id enum:
        CTF_TYPE_SEQUENCE,
        NR_CTF_TYPES.
 
-Depending on the field type, we can get informations about the field with these
-functions:
+Depending on the field type, we can get informations about the field with the
+following functions:
        * bt_ctf_get_index()            return the element at the index
                                        position of an array of a sequence;
 
@@ -166,7 +185,13 @@ functions:
                                                CTF_STRING_ASCII,
                                                CTF_STRING_UNKNOWN.
 
-These functions give access to the value associated with a field :
+All of these functions require a field declaration as parameter, depending on
+the source type of data (struct definition* or struct bt_ctf_field_decl*), the
+user might have to call bt_ctf_get_decl_from_def() or
+bt_ctf_get_decl_from_field_decl().
+
+The following functions give access to the value associated with a field
+defintion:
        * bt_ctf_get_uint64();
        * bt_ctf_get_int64();
        * bt_ctf_get_char_array();

diff --git a/include/babeltrace/ctf/events.h b/include/babeltrace/ctf/events.h
index 461cf06ccdd9c63040e45719f1a48b88154e6f29..57e067e9d7fa3ccc0bc1cee3131412d657c276fb 100644 (file)
--- a/include/babeltrace/ctf/events.h
+++ b/include/babeltrace/ctf/events.h
@@ -109,9 +109,9 @@ uint64_t bt_ctf_get_timestamp(const struct bt_ctf_event *event);
 /*
  * bt_ctf_get_field_list: obtain the list of fields for compound type
  *
- * This function can be used to obtain the list of fields 
- * contained within a compound type: array, sequence,
- * structure, or variant.
+ * This function can be used to obtain the list of fields contained
+ * within a top-level scope of an event or a compound type: array,
+ * sequence, structure, or variant.
 
  * This function sets the "list" pointer to an array of definition
  * pointers and set count to the number of elements in the array.
@@ -232,10 +232,16 @@ char *bt_ctf_get_string(const struct definition *field);
 int bt_ctf_field_get_error(void);
 
 /*
- * bt_ctf_get_event_decl_list: set list pointer to an array of bt_ctf_event_decl
- * pointers and set count to the number of elements in the array.
+ * bt_ctf_get_event_decl_list: get a list of all the event declarations in
+ * a trace.
+ *
+ * The list array is pointed to the array of event declarations.
+ * The number of events in the array is written in count.
  *
  * Return 0 on success and a negative value on error.
+ *
+ * The content pointed to by "list" should *not* be freed. It stays
+ * valid as long as the trace is opened.
  */
 int bt_ctf_get_event_decl_list(int handle_id, struct bt_context *ctx,
                struct bt_ctf_event_decl * const **list,
@@ -247,10 +253,15 @@ int bt_ctf_get_event_decl_list(int handle_id, struct bt_context *ctx,
 const char *bt_ctf_get_decl_event_name(const struct bt_ctf_event_decl *event);
 
 /*
- * bt_ctf_get_decl_fields: set list pointer to an array of bt_ctf_field_decl
- * pointers and set count to the number of elements in the array.
+ * bt_ctf_get_decl_fields: get all field declarations in a scope of an event
+ *
+ * The list array is pointed to the array of field declaration.
+ * The number of field declaration in the array is written in count.
  *
  * Returns 0 on success and a negative value on error
+ *
+ * The content pointed to by "list" should *not* be freed. It stays
+ * valid as long as the trace is opened.
  */
 int bt_ctf_get_decl_fields(struct bt_ctf_event_decl *event_decl,
                enum bt_ctf_scope scope,

diff --git a/include/babeltrace/trace-handle.h b/include/babeltrace/trace-handle.h
index 426800d84e4cf1d01056b6310233bf1eefd2ad92..f4c44065bf6e8ef0654d7992a44081d78674b471 100644 (file)
--- a/include/babeltrace/trace-handle.h
+++ b/include/babeltrace/trace-handle.h
@@ -54,7 +54,7 @@ uint64_t bt_trace_handle_get_timestamp_begin(struct bt_context *ctx,
 
 /*
  * bt_trace_handle_get_timestamp_end : returns the destruction timestamp
- * (in anoseconds or cycles depending on type) of the buffers of a trace
+ * (in nanoseconds or cycles depending on type) of the buffers of a trace
  * or -1ULL on error.
  */
 uint64_t bt_trace_handle_get_timestamp_end(struct bt_context *ctx,