From 696a5d4b917332d9e2d8ed288ac22b2411d3faa5 Mon Sep 17 00:00:00 2001
From: Simon Cruanes <simon.cruanes.2007@m4x.org>
Date: Mon, 12 Jan 2026 20:57:10 -0500
Subject: [PATCH] tidy up src/lib

---
 src/lib/logger.ml          |  2 ++
 src/lib/main_exporter.ml   | 21 +++++++++++++--------
 src/lib/metrics_emitter.ml |  4 ++++
 src/lib/tracer.ml          |  2 ++
 4 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/src/lib/logger.ml b/src/lib/logger.ml
index da84bfb0..6fb458d1 100644
--- a/src/lib/logger.ml
+++ b/src/lib/logger.ml
@@ -1,5 +1,7 @@
 (** Logs.
 
+    The logger is an object that can be used to emit logs.
+
     See
     {{:https://opentelemetry.io/docs/reference/specification/overview/#log-signal}
      the spec} *)
diff --git a/src/lib/main_exporter.ml b/src/lib/main_exporter.ml
index 318203ef..76f076f6 100644
--- a/src/lib/main_exporter.ml
+++ b/src/lib/main_exporter.ml
@@ -1,6 +1,8 @@
-(** Main exporter, used by the main tracing functions.
+(** Main exporter.
 
-    It is better to pass an explicit exporter when possible. *)
+    This is a singleton exporter, or [None] if not defined. It is better to pass
+    an explicit exporter when possible, but this is quite convenient and most
+    programs only need one exporter. *)
 
 open Exporter
 
@@ -26,7 +28,7 @@ let remove ~on_done () : unit =
     shutdown exp
 
 (** Is there a configured exporter? *)
-let present () : bool = Option.is_some (Atomic.get exporter)
+let[@inline] present () : bool = Option.is_some (Atomic.get exporter)
 
 (** Current exporter, if any *)
 let[@inline] get () : t option = Atomic.get exporter
@@ -38,8 +40,11 @@ let add_on_tick_callback f =
 module Util = struct
   open Opentelemetry_emitter
 
-  (** An emitter that uses the current main *)
-  let dynamic_forward_to_main_exporter ~get_emitter () : _ Emitter.t =
+  (** An emitter that uses the corresponding emitter in the current main
+      exporter. When this emitter is used to [emit signals], the current
+      exporter is looked up, [get_emitter exporter] is then used to locate the
+      relevant emitter [e'], and [signals] is in turn emitted in [e']. *)
+  let dynamic_forward_emitter_to_main_exporter ~get_emitter () : _ Emitter.t =
     let enabled () = present () in
     let closed () = not (enabled ()) in
     let flush_and_close () = () in
@@ -72,15 +77,15 @@ let[@inline] active () : Aswitch.t =
     @since NEXT_RELEASE *)
 let dynamic_forward_to_main_exporter : Exporter.t =
   let emit_logs =
-    Util.dynamic_forward_to_main_exporter ()
+    Util.dynamic_forward_emitter_to_main_exporter ()
       ~get_emitter:Exporter.(fun e -> e.emit_logs)
   in
   let emit_metrics =
-    Util.dynamic_forward_to_main_exporter ()
+    Util.dynamic_forward_emitter_to_main_exporter ()
       ~get_emitter:Exporter.(fun e -> e.emit_metrics)
   in
   let emit_spans =
-    Util.dynamic_forward_to_main_exporter ()
+    Util.dynamic_forward_emitter_to_main_exporter ()
       ~get_emitter:Exporter.(fun e -> e.emit_spans)
   in
   let on_tick f =
diff --git a/src/lib/metrics_emitter.ml b/src/lib/metrics_emitter.ml
index 97f53399..05d8318f 100644
--- a/src/lib/metrics_emitter.ml
+++ b/src/lib/metrics_emitter.ml
@@ -1,3 +1,7 @@
+(** Metrics.
+
+    The metrics emitter is used to, well, emit metrics. *)
+
 open Opentelemetry_emitter
 
 type t = {
diff --git a/src/lib/tracer.ml b/src/lib/tracer.ml
index 56ea4106..f79ef177 100644
--- a/src/lib/tracer.ml
+++ b/src/lib/tracer.ml
@@ -1,5 +1,7 @@
 (** Traces.
 
+    The tracer is an object that can be used to emit spans that form a trace.
+
     See
     {{:https://opentelemetry.io/docs/reference/specification/overview/#tracing-signal}
      the spec} *)