more docs

src/client/batch.mli

@@ -1,4 +1,4 @@
-(** A thread-safe batch of resources, to be sent together when ready . *)
+(** A thread-safe batch of resources, to be sent together when ready. *)
 
 type 'a t
 

src/client/consumer.ml

@@ -1,4 +1,4 @@
-(** Consumer that accepts items from a bounded queue *)
+(** Consumer that accepts items from a bounded queue and processes them. *)
 
 open Common_
 

src/client/emitter_combine.ml

@@ -1,4 +1,4 @@
-(** Combine multiple emitters into one *)
+(** Combine multiple emitters into one. *)
 
 open Opentelemetry_emitter.Emitter
 

src/client/export_error.ml

@@ -1,3 +1,5 @@
+(** Error that can occur during export *)
+
 type t =
   [ `Status of int * Opentelemetry.Proto.Status.status
   | `Failure of string

src/client/exporter_add_batching.ml

@@ -1,4 +1,8 @@
-(** Add batching to emitters *)
+(** Add batching to the emitters of an exporter.
+
+    The exporter has multiple emitters (one per signal type), this can add
+    batching on top of each of them (so that they emit less frequent, larger
+    batches of signals, amortizing the per-signal cost). *)
 
 open Common_
 

src/client/exporter_combine.ml

@@ -1,3 +1,5 @@
+(** Combine multiple exporters into one *)
+
 open Common_
 open Opentelemetry_atomic
 

src/client/exporter_debug.ml

@@ -1,3 +1,8 @@
+(** Basic debug exporter, prints signals on stdout/stderr/...
+
+    As the name says, it's not intended for production but as a quick way to
+    export signals and eyeball them. *)
+
 open Common_
 open Opentelemetry_emitter
 

src/client/exporter_queued.ml

@@ -1,4 +1,11 @@
-(** Build an exporter from a queue and a consumer *)
+(** Build an exporter from a queue and a consumer.
+
+    The exporter will send signals into the queue (possibly dropping them if the
+    queue is full), and the consumer is responsible for actually exporting the
+    signals it reads from the other end of the queue.
+
+    At shutdown time, the queue is closed for writing, but only once it's empty
+    will the consumer properly shutdown. *)
 
 open Common_
 module BQ = Bounded_queue

src/client/exporter_stdout.ml

@@ -1,4 +1,4 @@
-(** A simple exporter that prints on stdout *)
+(** A simple exporter that prints on stdout. *)
 
 open Common_
 open Opentelemetry_emitter

src/client/generic_io.ml

@@ -1,4 +1,7 @@
-(** Generic IO *)
+(** Generic IO monad.
+
+    This factors out some logic between various concurrency frameworks. *)
+
 module type S = sig
   type 'a t
 

src/client/generic_notifier.ml

@@ -1,3 +1,5 @@
+(** Generic notifier (used to signal when a bounded queue is empty) *)
+
 module type IO = Generic_io.S
 
 module type S = sig

src/client/sampler.mli

@@ -1,4 +1,4 @@
-(** Basic random sampling *)
+(** Basic random sampling. *)
 
 type t
 
@@ -16,10 +16,12 @@ val accept : t -> bool
 val proba_accept : t -> float
 
 val actual_rate : t -> float
-(** The ratio of signals we actually accepted so far *)
+(** The ratio of signals we actually accepted so far. This should asymptotically
+    be equal to {!proba_accept} if the random generator is good. *)
 
 open Opentelemetry_emitter
 
 val wrap_emitter : t -> 'a Emitter.t -> 'a Emitter.t
 (** [wrap_emitter sampler e] is a new emitter that uses the [sampler] on each
-    individual signal before passing them to [e]. *)
+    individual signal before passing them to [e]. This means only [proba_accept]
+    of the signals will actually be emitted. *)

src/client/self_trace.mli

@@ -1,4 +1,5 @@
-(** Mini tracing module (disabled if [config.self_trace=false]) *)
+(** Mini tracing module for OTEL itself (disabled if [config.self_trace=false])
+*)
 
 open Common_