trace: Comments and configure fix

Signed-off-by: David Goulet <dgoulet@torproject.org>

configure.ac

@@ -2768,16 +2768,16 @@ test "x$enable_oss_fuzz" = "xyes" && value=1 || value=0
 PPRINT_PROP_BOOL([OSS-Fuzz support (--enable-oss-fuzz)], $value)
 
 AS_ECHO
-PPRINT_SUBTITLE([Tracing])
+PPRINT_SUBTITLE([Tracing (--enable-tracing-instrumentation-<type>)])
 
 test "x$enable_tracing_instrumentation_log_debug" = "xyes" && value=1 || value=0
-PPRINT_PROP_BOOL([Tracepoints to log_debug() (--enable-tracing-instrumentation-log-debug)], $value)
+PPRINT_PROP_BOOL([Tracepoints to log_debug() (log-debug)], $value)
 
 test "x$enable_tracing_instrumentation_usdt" = "xyes" && value=1 || value=0
-PPRINT_PROP_BOOL([USDT Instrumentation (--enable-tracing-instrumentation-usdt)], $value)
+PPRINT_PROP_BOOL([USDT Instrumentation (usdt)], $value)
 
 test "x$enable_tracing_instrumentation_lttng" = "xyes" && value=1 || value=0
-PPRINT_PROP_BOOL([LTTng Instrumentation (--enable-tracing-instrumentation-lttng)], $value)
+PPRINT_PROP_BOOL([LTTng Instrumentation (lttng)], $value)
 
 AS_ECHO
 PPRINT_SUBTITLE([Install Directories])

src/lib/trace/events.h

@@ -9,7 +9,30 @@
 #ifndef TOR_LIB_TRACE_EVENTS_H
 #define TOR_LIB_TRACE_EVENTS_H
 
-/* XXX: DOCDOC once framework is stable. */
+/*
+ * A tracepoint signature is defined as follow:
+ *
+ *    tor_trace(<subsystem>, <event_name>, <args>...)
+ *
+ * If tracing is enabled, the tor_trace() macro is mapped to all possible
+ * instrumentations (defined below). Each instrumentation type MUST define a
+ * top level macro (TOR_TRACE_<type>) so it can be inserted into each
+ * tracepoint.
+ *
+ * In case no tracing is enabled (HAVE_TRACING), tracepoints are NOP and thus
+ * have no execution cost.
+ *
+ * Currently, three types of instrumentation are supported:
+ *
+ *  log-debug: Every tracepoints is mapped to a log_debug() statement.
+ *
+ *  User Statically-Defined Tracing (USDT): Probes that can be used with perf,
+ *  dtrace, SystemTap, DTrace and BPF Compiler Collection (BCC).
+ *
+ *  LTTng-UST: Probes for the LTTng Userspace Tracer. If USDT interface
+ *  (sdt.h) is available, the USDT probes are also generated by LTTng thus
+ *  enabling this instrumentation provides both probes.
+ */
 
 #ifdef HAVE_TRACING