improve docs

lib/hex.ml

@@ -90,11 +90,7 @@ let to_helper ~empty_return ~create ~set (`Hex s) =
     buf
 
 let to_string hex =
-  to_helper
-    ~empty_return:""
-    ~create:(Bytes.create)
-    ~set:(Bytes.set)
-    hex
+  to_helper ~empty_return:"" ~create:Bytes.create ~set:Bytes.set hex
 
 let of_cstruct ?(ignore=[]) cs =
   let open Cstruct in
@@ -108,10 +104,7 @@ let empty_cstruct = Cstruct.of_string ""
 
 let to_cstruct hex =
   to_helper
-    ~empty_return:empty_cstruct
-    ~create:(Cstruct.create)
-    ~set:(Cstruct.set_char)
-    hex
+    ~empty_return:empty_cstruct ~create:Cstruct.create ~set:Cstruct.set_char hex
 
 let hexdump_s ?(print_row_numbers=true) ?(print_chars=true) (`Hex s) =
   let char_len = 16 in (* row width in # chars *)

lib/hex.mli

@@ -15,9 +15,15 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  *)
 
-(** Hexadecimal encoding. *)
+(** Hexadecimal encoding.
 
-(** {2 Char} *)
+    [Hex] defines hexadecimal encodings for {{!char}characters},
+    {{!string}strings} and {{!cstruct}Cstruct.t} buffers. *)
+
+type t = [`Hex of string]
+(** The type var hexadecimal values. *)
+
+(** {1:char Characters} *)
 
 val of_char: char -> char * char
 (** [of_char c] is the the hexadecimal encoding of the character
@@ -27,43 +33,44 @@ val to_char: char -> char -> char
 (** [to_char x y] is the character correspondong to the [xy]
     hexadecimal encoding. *)
 
-(** {2 Strings} *)
-
-type t = [`Hex of string]
-(** The type of hexadecimal encodings. *)
+(** {1:string Strings} *)
 
 val of_string: ?ignore:char list -> string -> t
 (** [of_string s] is the hexadecimal representation of the binary
-    string [s]. If [ignore] is set, skip the characters in the list when
-    converting. Eg [of_string ~ignore:[' '] "a f"].
-    The default value of [ignore] is [[]]) *)
+    string [s]. If [ignore] is set, skip the characters in the list
+    when converting. Eg [of_string ~ignore:[' '] "a f"]. The default
+    value of [ignore] is [[]]). *)
 
 val to_string: t -> string
-(** [to_string h] is binary string corresponding to the hexadecimal
-    encoding [h]. The decoding function will skip whitespaces, tabs
-    and newlines. *)
+(** [to_string t] is the binary string [s] such that [of_string s] is
+    [t]. *)
 
-(** {2 Cstruct} *)
+(** {1:cstruct Cstruct} *)
 
 val of_cstruct: ?ignore:char list -> Cstruct.t -> t
-(** See [of_string] *)
+(** [of_cstruct buf] is the hexadecimal representation of the buffer
+    [buf]. *)
 
 val to_cstruct: t -> Cstruct.t
-(** See [to_string] *)
+(** [to_cstruct t] is the buffer [b] such that [of_cstruct b] is
+    [t]. *)
 
-(** {2 Debugging} *)
+(** {1 Debugging} *)
 
 val hexdump: ?print_row_numbers:bool -> ?print_chars:bool -> t -> unit
 (** [hexdump h] dumps the hex encoding to stdout in the following format:
 
-    [{00000000: 6865 6c6c 6f20 776f 726c 6420 6865 6c6c  hello world hell
-    00000010: 6f20 776f 726c 640a                      o world.}]
+    [{
+    00000000: 6865 6c6c 6f20 776f 726c 6420 6865 6c6c  hello world hell
+    00000010: 6f20 776f 726c 640a                      o world.
+    }]
 
-    This is the same format as emacs hexl-mode, and is a very similar format
-    to hexdump -C. '\t' and '\n' are printed as '.'.in the char column.
+    This is the same format as emacs hexl-mode, and is a very similar
+    format to hexdump -C. '\t' and '\n' are printed as '.'.in the char
+    column.
 
-    [print_row_numbers] and [print_chars] both default to [true]. Setting
-    either to [false] does not print the column.
+    [print_row_numbers] and [print_chars] both default to
+    [true]. Setting either to [false] does not print the column.
 *)
 
 val hexdump_s: ?print_row_numbers:bool -> ?print_chars:bool -> t -> string