bit of doc

src/core/trace_core.mli

@@ -1,4 +1,8 @@
-(** Trace. *)
+(** Main tracing interface.
+
+    This interface is intended to be lightweight and usable in both libraries
+    and applications. It has very low overhead if no {!Collector.t} is
+    installed. *)
 
 include module type of Types
 module Collector = Collector

src/debug/track_spans.mli

@@ -1,3 +1,5 @@
+(** Helper to track which spans never get closed. *)
+
 open Trace_core
 
 type unclosed_spans = {

src/tef/trace_tef.mli

@@ -1,3 +1,11 @@
+(** TEF collector for Trace.
+
+    This emits chrome traces
+    (https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/),
+    which are very simple and a known quantity.
+
+    They can be opened in https://ui.perfetto.dev . *)
+
 module Collector_tef = Collector_tef
 module Exporter = Exporter
 module Writer = Writer

src/trace.ml

@@ -1 +1,7 @@
+(** Shim that just forwards to {!Trace_core}.
+
+    The reason is, [Trace] is already defined in the compiler libs and can clash
+    with this module inside a toplevel. So it's safer to only depend on
+    [Trace_core] in libraries that might end up used in a toplevel. *)
+
 include Trace_core