From cc6c311b45b37c37dd416a451ab1b1017a3979a7 Mon Sep 17 00:00:00 2001
From: Simon Cruanes <simon.cruanes.2007@m4x.org>
Date: Tue, 10 Sep 2024 10:43:44 -0400
Subject: [PATCH] more docs

---
 src/subscriber/callbacks.ml  | 13 ++++++++++---
 src/subscriber/subscriber.ml | 10 +++++++++-
 2 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/src/subscriber/callbacks.ml b/src/subscriber/callbacks.ml
index 48a73a8..3ff7647 100644
--- a/src/subscriber/callbacks.ml
+++ b/src/subscriber/callbacks.ml
@@ -1,8 +1,10 @@
 open Trace_core
 open Types
 
+(** First class module signature for callbacks *)
 module type S = sig
   type st
+  (** Type of the state passed to every callback. *)
 
   val on_init : st -> time_ns:float -> unit
   (** Called when the subscriber is initialized in a collector *)
@@ -85,10 +87,14 @@ module type S = sig
 end
 
 type 'st t = (module S with type st = 'st)
+(** Callbacks for a subscriber. There is one callback per event
+    in {!Trace}. The type ['st] is the state that is passed to
+    every single callback. *)
 
-(** Callbacks for a subscriber *)
-
-(** Dummy callbacks *)
+(** Dummy callbacks.
+    It can be useful to reuse some of these functions in a
+    real subscriber that doesn't want to handle {b all}
+    events, but only some of them. *)
 module Dummy = struct
   let on_init _ ~time_ns:_ = ()
   let on_shutdown _ ~time_ns:_ = ()
@@ -113,6 +119,7 @@ module Dummy = struct
     ()
 end
 
+(** Dummy callbacks, do nothing. *)
 let dummy (type st) () : st t =
   let module M = struct
     type nonrec st = st
diff --git a/src/subscriber/subscriber.ml b/src/subscriber/subscriber.ml
index 8ecf0a8..0246984 100644
--- a/src/subscriber/subscriber.ml
+++ b/src/subscriber/subscriber.ml
@@ -1,4 +1,9 @@
-(** A trace subscriber *)
+(** A trace subscriber. It pairs a set of callbacks
+    with the state they need (which can contain a file handle,
+    a socket, config, etc.).
+
+    The design goal for this is that it should be possible to avoid allocations
+    when the trace collector calls the callbacks. *)
 type t =
   | Sub : {
       st: 'st;
@@ -6,6 +11,7 @@ type t =
     }
       -> t
 
+(** Dummy subscriber that ignores every call. *)
 let dummy : t = Sub { st = (); callbacks = Callbacks.dummy () }
 
 open struct
@@ -91,6 +97,8 @@ open struct
   end
 end
 
+(** [tee s1 s2] is a subscriber that forwards every
+    call to [s1] and [s2] both. *)
 let tee (s1 : t) (s2 : t) : t =
   let st = s1, s2 in
   Sub { st; callbacks = (module Tee_cb) }