From e95fe8f77661e2915c9e97a945d608c480c0d8a6 Mon Sep 17 00:00:00 2001
From: pmf <pmf@04897980-b3bd-0310-b5e0-8ef037075253>
Date: Fri, 30 May 2008 15:15:24 +0000
Subject: [PATCH] liblttvtraceread: add documentation

git-svn-id: http://ltt.polymtl.ca/svn@2926 04897980-b3bd-0310-b5e0-8ef037075253
---
 ltt/branches/poly/ltt/tracefile.c | 23 +++++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

diff --git a/ltt/branches/poly/ltt/tracefile.c b/ltt/branches/poly/ltt/tracefile.c
index 31100215..c301950a 100644
--- a/ltt/branches/poly/ltt/tracefile.c
+++ b/ltt/branches/poly/ltt/tracefile.c
@@ -949,6 +949,11 @@ seek_error:
   return err;
 }
 
+/*
+ * Open a trace and return its LttTrace handle.
+ *
+ * pathname must be the directory of the trace
+ */
 
 LttTrace *ltt_trace_open(const gchar *pathname)
 {
@@ -1044,16 +1049,23 @@ alloc_error:
 
 }
 
-/******************************************************************************
+/* Open another, completely independant, instance of a trace.
+ *
+ * A read on this new instance will read the first event of the trace.
+ * 
  * When we copy a trace, we want all the opening actions to happen again :
  * the trace will be reopened and totally independant from the original.
  * That's why we call ltt_trace_open.
- *****************************************************************************/
+ */
 LttTrace *ltt_trace_copy(LttTrace *self)
 {
   return ltt_trace_open(g_quark_to_string(self->pathname));
 }
 
+/*
+ * Close a trace
+ */
+
 void ltt_trace_close(LttTrace *t)
 {
   g_datalist_clear(&t->tracefiles);
@@ -1251,6 +1263,8 @@ fail:
   return EPERM;
 }
 
+/* Seek to a position indicated by an LttEventPosition
+ */
 
 int ltt_tracefile_seek_position(LttTracefile *tf, const LttEventPosition *ep)
 {
@@ -1285,6 +1299,10 @@ fail:
   return 1;
 }
 
+/* Given a TSC value, return the LttTime (seconds,nanoseconds) it
+ * corresponds to.
+ */
+
 LttTime ltt_interpolate_time_from_tsc(LttTracefile *tf, guint64 tsc)
 {
   LttTime time;
@@ -1385,6 +1403,7 @@ int ltt_tracefile_read_seek(LttTracefile *tf)
   return 0;
 }
 
+/* do an operation when reading a new event */
 
 /* do specific operation on events */
 int ltt_tracefile_read_op(LttTracefile *tf)
-- 
2.34.1