Docs for tls.h and trace.h.

src/trace.h

@@ -3,32 +3,103 @@
 /**
 ** \defgroup trace Performance Tracing
 ** Generates trace output that is compatible with speedscope.app,
-** chrome://tracing or ui.perfetto.dev for scrutining what each thread is doing
-** for optimization purposes.
+** chrome://tracing or ui.perfetto.dev for scrutinizing what each thread is
+** doing for optimization purposes.
 ** @{
 */
 
 #include <inttypes.h>
 #include <stddef.h>
 
+/**
+** A trace instance.
+*/
 typedef struct _tf_trace_t tf_trace_t;
+
+/**
+** An SQLite database instance.
+*/
 typedef struct sqlite3 sqlite3;
 
+/**
+** Create a trace instance.  Can be used to produce a Chrome trace event
+** document for analyzing performance.  Clean up with tf_trace_destroy().
+** @return A trace instance.
+*/
 tf_trace_t* tf_trace_create();
+
+/**
+** Destroy a trace instance that was created with tf_trace_create().
+*/
 void tf_trace_destroy(tf_trace_t* trace);
 
+/**
+** Set the name of the current process.
+** @param trace The trace instance.
+** @param name The name of the process.
+*/
 void tf_trace_set_process_name(tf_trace_t* trace, const char* name);
 
+/**
+** Record counter values.
+** @param trace The trace instance.
+** @param name The counter group name.
+** @param argc The number of counters.
+** @param arg_names The counter names.
+** @param arg_values The counter values.
+*/
 void tf_trace_counter(tf_trace_t* trace, const char* name, int argc, const char** arg_names, const int64_t* arg_values);
+
+/**
+** Begin tracing a time interval.  End with tf_trace_end().
+** @param trace The trace instance.
+** @param name The interval name.
+*/
 void tf_trace_begin(tf_trace_t* trace, const char* name);
+
+/**
+** End tracing the next time interval previously started with tf_trace_begin().
+** @param trace The trace instance.
+*/
 void tf_trace_end(tf_trace_t* trace);
 
+/**
+** Export all currently stored trace data to a string.
+** @param trace The trace instance.
+** @return A string representation of the trace data.
+*/
 char* tf_trace_export(tf_trace_t* trace);
 
+/**
+** A callback to collect trace data.
+** @param trace The trace instance.
+** @param buffer The trace data.
+** @param size The size of the trace data.
+** @param user_data User data registered with the callback.
+*/
 typedef void(tf_trace_write_callback_t)(tf_trace_t* trace, const char* buffer, size_t size, void* user_data);
+
+/**
+** Replace the trace recording behavior.
+** @param trace The trace instance.
+** @param callback A callback that will be called instead of collecting the trace data in a buffer.
+** @param user_data User data to pass to the callback.
+*/
 void tf_trace_set_write_callback(tf_trace_t* trace, tf_trace_write_callback_t* callback, void* user_data);
+
+/**
+** Inject raw trace data.
+** @param trace The trace instance.
+** @param buffer The trace data.
+** @param size The size of the trace data.
+*/
 void tf_trace_raw(tf_trace_t* trace, const char* buffer, size_t size);
 
+/**
+** Register for trace-worthy events from sqlite and record them going forward.
+** @param trace The trace instance.
+** @param sqlite The SQLite database.
+*/
 void tf_trace_sqlite(tf_trace_t* trace, sqlite3* sqlite);
 
 /** @} */