From c7a25a1618d59e0e657b18aaee2e59db9c2a9738 Mon Sep 17 00:00:00 2001
From: Simon Cruanes <simon.cruanes.2007@m4x.org>
Date: Mon, 12 Jun 2023 11:06:45 -0400
Subject: [PATCH] more docs

---
 src/collector.ml |  4 ++++
 src/trace.mli    | 47 ++++++++++++++++++++++++++++++++++++++++-------
 src/types.ml     |  7 +++++--
 3 files changed, 49 insertions(+), 9 deletions(-)

diff --git a/src/collector.ml b/src/collector.ml
index 0539c0e..11c6447 100644
--- a/src/collector.ml
+++ b/src/collector.ml
@@ -9,6 +9,10 @@ open Types
 
 let dummy_span : span = Int64.min_int
 
+(** Signature for a collector.
+
+    This is only relevant to implementors of tracing backends; to instrument
+    your code you only need to look at the {!Trace} module. *)
 module type S = sig
   val enter_span :
     ?__FUNCTION__:string ->
diff --git a/src/trace.mli b/src/trace.mli
index f36a5aa..d78b33b 100644
--- a/src/trace.mli
+++ b/src/trace.mli
@@ -18,8 +18,21 @@ val enter_span :
   ?data:(unit -> (string * user_data) list) ->
   string ->
   span
+(** Enter a span. A span is a delimited period of time with
+    a start instant ("enter") and stop instant ("exit"), associated
+    with some metadata about the code entering/exiting some piece of code.
+
+    In particular the entrypoint comes with the location of the code
+    (you can use [__FILE__] and [__LINE__] directly in OCaml),
+    a mandatory name, and some optional metadata in a JSON-like representation.
+*)
 
 val exit_span : span -> unit
+(** Exit the span.
+
+    This should be called exactly once per span (even in case of exception).
+    Once this is called, a timestamp might be recorded,
+  and the span is considered finished and can't be used anymore *)
 
 val with_span :
   ?__FUNCTION__:string ->
@@ -29,40 +42,60 @@ val with_span :
   string ->
   (span -> 'a) ->
   'a
+(** [with_span ~__FILE__ ~__LINE__ name f] enters a new span [sp],
+    and calls [f sp].
+    [sp] might be a dummy span if no collector is installed.
+    When [f sp] returns or raises, the span [sp] is exited.
+
+    This is the recommended way to instrument most code. *)
 
 val message :
   ?span:span -> ?data:(unit -> (string * user_data) list) -> string -> unit
-
-(* TODO: counter/plot/metric *)
+(** [message msg] logs a message [msg] (if a collector is installed).
+    Additional metadata can be provided.
+    @param span the surrounding span, if any. This might be ignored by the collector. *)
 
 val messagef :
   ?span:span ->
   ?data:(unit -> (string * user_data) list) ->
   ((('a, Format.formatter, unit, unit) format4 -> 'a) -> unit) ->
   unit
+(** [messagef (fun k->k"hello %s %d!" "world" 42)] is like
+    [message "hello world 42!"] but only computes the string formatting
+    if a collector is installed. *)
 
 val set_thread_name : string -> unit
-(** Give a name to the current thread. *)
+(** Give a name to the current thread.
+    This might be used by the collector
+    to display traces in a more informative way. *)
 
 val set_process_name : string -> unit
-(** Give a name to the current process. *)
+(** Give a name to the current process.
+    This might be used by the collector
+    to display traces in a more informative way. *)
 
 val counter_int : string -> int -> unit
-(** Emit a counter (int) *)
+(** Emit a counter of type [int]. Counters represent the evolution of some quantity
+    over time. *)
 
 val counter_float : string -> float -> unit
-(** Emit a counter (float) *)
+(** Emit a counter of type [float]. See {!counter_int} for more details. *)
 
 (** {2 Collector} *)
 
 type collector = (module Collector.S)
+(** An event collector.
+
+    See {!Collector} for more details. *)
 
 val setup_collector : collector -> unit
-(** [setup_collector c] installs [c] as the collector.
+(** [setup_collector c] installs [c] as the current collector.
     @raise Invalid_argument if there already is an established
     collector. *)
 
 val shutdown : unit -> unit
+(** [shutdown ()] shutdowns the current collector, if one was installed,
+    and waits for it to terminate before returning. *)
 
 (**/**)
 
diff --git a/src/types.ml b/src/types.ml
index ba0cfa4..5ba3487 100644
--- a/src/types.ml
+++ b/src/types.ml
@@ -1,5 +1,7 @@
 type span = int64
-(** A span identifier. *)
+(** A span identifier.
+
+    The meaning of the identifier depends on the collector. *)
 
 type user_data =
   [ `Int of int
@@ -7,4 +9,5 @@ type user_data =
   | `Bool of bool
   | `None
   ]
-(** User defined data, generally passed as key/value pairs *)
+(** User defined data, generally passed as key/value pairs to
+    whatever collector is installed (if any). *)