doc: more docs for codegen

src/codegen/containers_codegen.mli

@@ -1,5 +1,36 @@
 
-(** {1 Code generators} *)
+(** {1 Code generators}
+
+    The code generator library is designed to be used from a build system
+    (for example, from [dune]) to generate efficient code for features
+    that are harder to provide at runtime.
+
+    The idea is that the build system should invoke some OCaml script
+    that depends on [containers.codegen]; the script uses the DSL below
+    to describe what code to generate (e.g. a description of a bitfield type)
+    and emits a [.ml] file (and possibly a [.mli] file).
+
+    For example, the build script might contain:
+
+{[
+module CG = Containers_codegen
+let () =
+  let module B = CG.Bitfield in
+  let b = B.make ~name:"t" () in
+  B.field_bit b "x";
+  B.field_bit b "y";
+  B.field_bit b "z";
+  B.field_int b ~width:5 "foo";
+
+  CG.emit_file "foo.mli" (B.gen_mli b);
+  CG.emit_file "foo.ml" (B.gen_ml b);
+  ()
+]}
+
+    and this will produce [foo.ml] and [foo.mli] with a bitfield containing
+    [x], [y], and [z].
+
+*)
 
 module Fmt = CCFormat
 
@@ -32,15 +63,31 @@ module Bitfield : sig
       assertion that {!Sys.int_size} is wide enough to support this type *)
 
   val field_bit : t -> string -> unit
+  (** [field_bit ty name] adds a field of size [1] to the bitfield [ty],
+      with name [name]. The generate code will provide get/set for
+      a boolean. *)
+
   val field_int : t -> width:int -> string -> unit
+(** [field_int ty name ~width] adds a field of size [width] to
+    the bitfield with name [name].
+    The accessors will be for integers of [width] bits, and the
+    setter might assert that the provided integer fits. *)
 
   val total_width : t -> int
+  (** Total width in bits of the given bitfield. *)
 
   val gen_mli : t -> code
+  (** Generate code for the type signature for the given bitfield *)
+
   val gen_ml : t -> code
+  (** Generate code for the implementation for the given bitfield *)
 end
 
 val emit_file : string -> code list -> unit
+(** [emit_file file cs] emits code fragments [cs] into the given file
+    at path [file] *)
+
 val emit_chan : out_channel -> code list -> unit
+
 val emit_string : code list -> string