chore: consistent maming of type vars and add missing comments (#15)

We make the naming of type variables consistent by using 'tag to
emphasize we are talking about the type of tags. We also add
documentation to functions in the API that were missing it.

Signed-off-by: Ali Caglayan <[email protected]>

src/pp.mli

@@ -7,31 +7,32 @@ type +'tag t
 (** {1 Basic combinators} *)
 
 (** A pretty printer that prints nothing *)
-val nop : _ t
+val nop : 'tag t
 
 (** [seq x y] prints [x] and then [y] *)
-val seq : 'a t -> 'a t -> 'a t
+val seq : 'tag t -> 'tag t -> 'tag t
 
 (** [concat ?sep l] prints elements in [l] separated by [sep]. [sep] defaults to
     [nop]. *)
-val concat : ?sep:'a t -> 'a t list -> 'a t
+val concat : ?sep:'tag t -> 'tag t list -> 'tag t
 
-(** Convenience function for [List.map] followed by [concat] *)
-val concat_map : ?sep:'a t -> 'b list -> f:('b -> 'a t) -> 'a t
+(** Convenience function for [List.map] followed by [concat]. *)
+val concat_map : ?sep:'tag t -> 'a list -> f:('a -> 'tag t) -> 'tag t
 
-val concat_mapi : ?sep:'a t -> 'b list -> f:(int -> 'b -> 'a t) -> 'a t
+(** Convenience function for [List.mapi] followed by [concat]. *)
+val concat_mapi : ?sep:'tag t -> 'a list -> f:(int -> 'a -> 'tag t) -> 'tag t
 
-(** An indivisible block of text *)
-val verbatim : string -> _ t
+(** An indivisible block of text. *)
+val verbatim : string -> 'tag t
 
-(** A single character *)
-val char : char -> _ t
+(** A single character. *)
+val char : char -> 'tag t
 
 (** Print a bunch of text. The line may be broken at any spaces in the text. *)
-val text : string -> _ t
+val text : string -> 'tag t
 
 (** Same as [text] but take a format string as argument. *)
-val textf : ('a, unit, string, _ t) format4 -> 'a
+val textf : ('a, unit, string, 'tag t) format4 -> 'a
 
 (** {1 Break hints} *)
 
@@ -41,22 +42,22 @@ val textf : ('a, unit, string, _ t) format4 -> 'a
 
     So for instance [verbatim "x" ++ space ++ verbatim "y"] might produce "x y"
     or "x\n<indentation>y". *)
-val space : _ t
+val space : 'tag t
 
 (** [cut] instructs the pretty-printing algorithm that the line may be broken at
     this point. If the algorithm decides not to break the line, nothing is
     printed instead.
 
     So for instance [verbatim "x" ++ space ++ verbatim "y"] might produce "xy"
     or "x\n<indentation>y". *)
-val cut : _ t
+val cut : 'tag t
 
 (** [break] is a generalisation of [space] and [cut]. It also instructs the
     pretty-printing algorithm that the line may be broken at this point. If it
     ends up being broken, [shift] will be added to the indentation level,
     otherwise [nspaces] spaces will be printed. [shift] can be negative, in
     which case the indentation will be reduced. *)
-val break : nspaces:int -> shift:int -> _ t
+val break : nspaces:int -> shift:int -> 'tag t
 
 (** [custom_break ~fits:(a, b, c) ~breaks:(x, y, z)] is a generalisation of
     [break]. It also instructs the pretty-printing algorithm that the line may
@@ -66,10 +67,13 @@ val break : nspaces:int -> shift:int -> _ t
     printed. The indentation [y] can be negative, in which case the indentation
     will be reduced. *)
 val custom_break :
-  fits:string * int * string -> breaks:string * int * string -> _ t
+  fits:string * int * string -> breaks:string * int * string -> 'tag t
 
-(** Force a newline to be printed *)
-val newline : _ t
+(** Force a newline to be printed. Usage is discourage since it breaks printing
+    with boxes. If you need to add breaks to your text, put your items into
+    [box]es and [concat] with a separating [space] afterwhich wrapping it in a
+    [vbox]. *)
+val newline : 'tag t
 
 (** {1 Boxes} *)
 
@@ -105,20 +109,20 @@ val newline : _ t
 (** Try to put as much as possible on each line. Additionally, a break hint
     always break the line if the breaking would reduce the indentation level
     inside the box ([break] with negative [shift] value). *)
-val box : ?indent:int -> 'a t -> 'a t
+val box : ?indent:int -> 'tag t -> 'tag t
 
 (** Always break the line when encountering a break hint. *)
-val vbox : ?indent:int -> 'a t -> 'a t
+val vbox : ?indent:int -> 'tag t -> 'tag t
 
 (** Print everything on one line, no matter what *)
-val hbox : 'a t -> 'a t
+val hbox : 'tag t -> 'tag t
 
 (** If possible, print everything on one line. Otherwise, behave as a [vbox] *)
-val hvbox : ?indent:int -> 'a t -> 'a t
+val hvbox : ?indent:int -> 'tag t -> 'tag t
 
 (** Try to put as much as possible on each line. Basically the same as [box] but
     without the rule about breaks with negative [shift] value. *)
-val hovbox : ?indent:int -> 'a t -> 'a t
+val hovbox : ?indent:int -> 'tag t -> 'tag t
 
 (** {1 Tags} *)
 
@@ -127,12 +131,14 @@ val hovbox : ?indent:int -> 'a t -> 'a t
     terminal with colors. *)
 
 (** [tag x t] Tag the material printed by [t] with [x] *)
-val tag : 'a -> 'a t -> 'a t
+val tag : 'tag -> 'tag t -> 'tag t
 
 (** Convert tags in a documents *)
-val map_tags : 'a t -> f:('a -> 'b) -> 'b t
+val map_tags : 'from_tag t -> f:('from_tag -> 'to_tag) -> 'to_tag t
 
-val filter_map_tags : 'a t -> f:('a -> 'b option) -> 'b t
+(** Convert tags in a documents, possibly removing some tags. *)
+val filter_map_tags :
+  'from_tag t -> f:('from_tag -> 'to_tag option) -> 'to_tag t
 
 (** {1 Convenience functions} *)
 
@@ -144,7 +150,7 @@ val filter_map_tags : 'a t -> f:('a -> 'b option) -> 'b t
       - item3
       ...
     v} *)
-val enumerate : 'a list -> f:('a -> 'b t) -> 'b t
+val enumerate : 'a list -> f:('a -> 'tag t) -> 'tag t
 
 (** [chain l ~f] is used to print a succession of items that follow each other.
     It produces an output of this form:
@@ -155,24 +161,26 @@ val enumerate : 'a list -> f:('a -> 'b t) -> 'b t
       -> item3
       ...
     v} *)
-val chain : 'a list -> f:('a -> 'b t) -> 'b t
+val chain : 'a list -> f:('a -> 'tag t) -> 'tag t
 
 (** {1 Operators} *)
 
 module O : sig
+  (** Infix operators for [Pp.t] *)
+
   (** Same as [seq] *)
-  val ( ++ ) : 'a t -> 'a t -> 'a t
+  val ( ++ ) : 'tag t -> 'tag t -> 'tag t
 end
 
 (** {1 Rendering} *)
 
 (** Render a document to a classic formatter *)
-val to_fmt : Format.formatter -> _ t -> unit
+val to_fmt : Format.formatter -> 'tag t -> unit
 
 val to_fmt_with_tags :
      Format.formatter
-  -> 'a t
-  -> tag_handler:(Format.formatter -> 'a -> 'a t -> unit)
+  -> 'tag t
+  -> tag_handler:(Format.formatter -> 'tag -> 'tag t -> unit)
   -> unit
 
 (** {1 Injection} *)
@@ -182,39 +190,39 @@ val to_fmt_with_tags :
     Disclaimer: this function is to meant to help using [Pp] in existing code
     that already use the [Format] module without having to port everything to
     [Pp]. It is not meant as the normal way to create [Pp.t] values. *)
-val of_fmt : (Format.formatter -> 'a -> unit) -> 'a -> _ t
+val of_fmt : (Format.formatter -> 'tag -> unit) -> 'tag -> 'tag t
 
 (** {1 Ast} *)
 
 module Ast : sig
   (** Stable representation useful for serialization *)
-  type 'a t =
+  type 'tag t =
     | Nop
-    | Seq of 'a t * 'a t
-    | Concat of 'a t * 'a t list
-    | Box of int * 'a t
-    | Vbox of int * 'a t
-    | Hbox of 'a t
-    | Hvbox of int * 'a t
-    | Hovbox of int * 'a t
+    | Seq of 'tag t * 'tag t
+    | Concat of 'tag t * 'tag t list
+    | Box of int * 'tag t
+    | Vbox of int * 'tag t
+    | Hbox of 'tag t
+    | Hvbox of int * 'tag t
+    | Hovbox of int * 'tag t
     | Verbatim of string
     | Char of char
     | Break of (string * int * string) * (string * int * string)
     | Newline
     | Text of string
-    | Tag of 'a * 'a t
+    | Tag of 'tag * 'tag t
 end
 
 (** [of_ast t] [Ast.t] to [Pp.t] *)
-val of_ast : 'a Ast.t -> 'a t
+val of_ast : 'tag Ast.t -> 'tag t
 
 (** [to_ast t] will try to convert [t] to [Ast.t]. When [t] contains values
     constructed with [of_fmt], this function will fail and return [Error ()] *)
-val to_ast : 'a t -> ('a Ast.t, unit) result
+val to_ast : 'tag t -> ('tag Ast.t, unit) result
 
 (** {1 Comparison} *)
 
 (** [compare cmp x y] compares [x] and [y] using [cmp] to compare tags.
 
     @raise Invalid_argument if two [of_fmt] values are compared. *)
-val compare : ('a -> 'a -> int) -> 'a t -> 'a t -> int
+val compare : ('tag -> 'tag -> int) -> 'tag t -> 'tag t -> int