Utils: various doc improvements

src/minutils/hex_encode.ml

@@ -9,7 +9,8 @@
 
 (* Tezos Utility library - Hexadecimal encoding *)
 
-(* From OCaml's stdlib. See [Digest.to_hex] *)
+(* From OCaml's stdlib. See [Digest.to_hex], and [hex_of_bytes], [hex_encode]
+   below for examples. *)
 let gen_encode length get s =
   let n = length s in
   let result = Bytes.create (n*2) in
@@ -21,7 +22,8 @@ let gen_encode length get s =
 let hex_of_bytes = gen_encode MBytes.length MBytes.get_uint8
 let hex_encode = gen_encode String.length (fun s i -> int_of_char s.[i])
 
-(* From OCaml's stdlib. See [Digest.from_hex]. *)
+(* From OCaml's stdlib. See [Digest.from_hex], and [hex_decode], [bytes_of_hex]
+   below for examples. *)
 let gen_decode create set h =
   let n = String.length h in
   if n mod 2 <> 0 then invalid_arg ("hex_decode: " ^ h);
@@ -45,41 +47,3 @@ let hex_decode s =
 
 let bytes_of_hex s =
   gen_decode MBytes.create MBytes.set_int8 s
-
-(*
-let hex_bytes =
-  let open Data_encoding in
-  let schema =
-     let open Json_schema in
-     create
-       { title = None ;
-         description = None ;
-         default = None;
-         enum = None;
-         kind = String {
-             pattern = Some "^[a-zA-Z0-9]+$";
-             min_length = 0;
-             max_length = None;
-           };
-         format = None ;
-         id = None } in
-  conv ~schema hex_of_bytes (Json.wrap_error bytes_of_hex) string
-
-let sha256 =
-  let open Data_encoding in
-  let schema =
-    let open Json_schema in
-    create
-      { title = None ;
-        description = None ;
-        default = None;
-        enum = None;
-        kind = String {
-            pattern = Some "^[a-zA-Z0-9]+$";
-            min_length = 64;
-            max_length = Some 64;
-          };
-        format = Some "sha256" ;
-        id = None } in
-  conv ~schema hex_of_bytes (Json.wrap_error bytes_of_hex) string
-*)

src/minutils/mBytes.mli

@@ -7,11 +7,18 @@
 (*                                                                        *)
 (**************************************************************************)
 
+(** Low-level byte array querying and manipulation.
+
+    Default layout for numeric operations is big-endian.
+    Little-endian operations in the LE submodule. **)
+
 open Bigarray
 
+(* Arrays are of characters, represented as uint8's, in row-major layout. *)
 type t = (char, int8_unsigned_elt, c_layout) Array1.t
 
 val create: int -> t
+(** [create n] allocates and returns an array of size [n] **)
 
 val length: t -> int
 
@@ -143,3 +150,4 @@ val (>) : t -> t -> bool
 val compare : t -> t -> int
 
 val concat: t -> t -> t
+(** Returns a new array with adjacent copies of the two input arrays **)

src/minutils/utils.ml

@@ -307,5 +307,5 @@ let parse_addr_port s =
                 check_port port ;
                 addr, port
             | _pos ->
-                invalid_arg "split_url_port: IPv6 addresses must be bracketed"
+                invalid_arg "Utils.parse_addr_port: IPv6 addresses must be bracketed"
   end

src/minutils/utils.mli

@@ -18,32 +18,57 @@ val split_path: string -> string list
     string, if [limit] is passed, stops after [limit] split(s). *)
 val split: char -> ?dup:bool -> ?limit: int -> string -> string list
 
+(** [Some (f x)] if input is [Some x], or [None] if it's [None] **)
 val map_option: f:('a -> 'b) -> 'a option -> 'b option
+
+(** [(f x)] if input is [Some x], or [None] if it's [None] **)
 val apply_option: f:('a -> 'b option) -> 'a option -> 'b option
+
+(** Call [(f x)] if input is [Some x], noop if it's [None] **)
 val iter_option: f:('a -> unit) -> 'a option -> unit
+
+(** [x] if input is [Some x], default if it's [None] **)
 val unopt: default:'a -> 'a option -> 'a
+
+(** [unopt_map f d x] is [y] if [x] is [Some y], [d] if [x] is [None] **)
 val unopt_map: f:('a -> 'b) -> default:'b -> 'a option -> 'b
+
+(** [x] for elements [Some x] in input. [None]s are dropped. **)
 val unopt_list: 'a option list -> 'a list
+
+(** First input of form [Some x], or [None] if none **)
 val first_some: 'a option -> 'a option -> 'a option
 
+(** Print a paragraph in a box **)
 val display_paragraph: Format.formatter -> string -> unit
 
 (** [remove nb list] remove the first [nb] elements from the list [list]. *)
 val remove_elem_from_list: int -> 'a list -> 'a list
+
+(** Return pair (list of first n items, remaining items) **)
 val split_list_at: int -> 'a list -> 'a list * 'a list
 
+(** [true] if input has prefix **)
 val has_prefix: prefix:string -> string -> bool
+
+(** Some (input with [prefix] removed), if string has [prefix], else [None] **)
 val remove_prefix: prefix:string -> string -> string option
+
+(** Length of common prefix of input strings *)
 val common_prefix: string -> string -> int
 
-
+(** [filter_map f l] is [[y for x in l where (f x) = Some y]] **)
 val filter_map: ('a -> 'b option) -> 'a list -> 'b list
 
-(** [list_rev_sub l n] is (List.rev l) capped to max n elements *)
+(** [list_rev_sub l n] is [List.rev l] capped to max [n] elements *)
 val list_rev_sub : 'a list -> int -> 'a list
-(** [list_sub l n] is l capped to max n elements *)
+(** [list_sub l n] is [l] capped to max [n] elements *)
 val list_sub: 'a list -> int -> 'a list
+
+(** Like [List.hd], but [Some hd] or [None] if empty **)
 val list_hd_opt: 'a list -> 'a option
+
+(** Last elt of list, or raise Not_found if empty **)
 val list_last_exn: 'a list -> 'a
 
 (** [merge_filter_list2 ~compare ~f l1 l2] merges two lists ordered by [compare]
@@ -65,9 +90,13 @@ val merge_list2 :
   'a list -> 'a list ->
   'a list
 
+(** [finalize f g ] ensures g() called after f(), even if exception raised **)
 val finalize: (unit -> 'a) -> (unit -> unit) -> 'a
 
+(** Return contents of file at given filename. **)
 val read_file: ?bin:bool -> string -> string
+
+(** [write_file p c] writes c to file at path p **)
 val write_file: ?bin:bool -> string -> string -> unit
 
 (** Compose functions from right to left. *)
@@ -76,9 +105,10 @@ val (<<) : ('b -> 'c) -> ('a -> 'b) -> 'a -> 'c
 (** Sequence: [i--j] is the sequence [i;i+1;...;j-1;j] *)
 val (--) : int -> int -> int list
 
+(** [repeat n x] is a list of [n] [x]'s **)
 val repeat: int -> 'a -> 'a list
 
-(** [take_n n l] returns the [n] first elements of [n]. When [compare]
+(** [take_n n l] returns the [n] first elements of [l]. When [compare]
     is provided, it returns the [n] greatest element of [l]. *)
 val take_n: ?compare:('a -> 'a -> int) -> int -> 'a list -> 'a list
 
@@ -90,8 +120,9 @@ module Bounded(E: Set.OrderedType) : sig
   val get: t -> E.t list
 end
 
+(** [select n l] is ([n]th element of [l], [l] without that element) **)
 val select: int -> 'a list -> 'a * 'a list
 
-(** [split_url_port uri] is (node, service) where [node] is the DNS or
+(** [parse_addr_port uri] is (node, service) where [node] is the DNS or
     IP and service is the optional port number or service name. *)
 val parse_addr_port: string -> string * string