improve documentation

doc/index.mld

@@ -1,12 +1,14 @@
 {0 scfg}
 
-{{:https://TODO} scfg} is an {{:https://ocaml.org} OCaml} library/executable to TODO.
+{{:https://git.zapashcanon.fr/zapashcanon/scfg} scfg} is an {{:https://ocaml.org} OCaml} library/executable to work with the {{:https://git.sr.ht/~emersion/scfg} scfg configuration file format}.
 
 {1:api API}
 
 
 {!modules:
-Scfg
+Scfg.Parse
+Scfg.Pp
+Scfg.Types
 }
 
 
@@ -15,5 +17,6 @@ Scfg
 You shouldn't have to use any of these modules, they're used internally only.
 
 {!modules:
-TODO
+Scfg.Lexer
+Scfg.Menhir_parser
 }

dune-project

@@ -1,5 +1,7 @@
 (lang dune 2.8)
 
+(implicit_transitive_deps false)
+
 (name scfg)
 
 (license ISC)

src/parse.ml

@@ -1,25 +1,29 @@
-let provider buf () =
-  let tok = Lexer.token buf in
-  let start, stop = Sedlexing.lexing_positions buf in
-  (tok, start, stop)
+(** Module providing functions to parse a config from various kind of inputs. *)
 
-let parser_result =
+(** Parse a config from a lexing buffer. *)
+let from_lexbuf =
   let parser =
     MenhirLib.Convert.Simplified.traditional2revised Menhir_parser.config
   in
-  fun buf -> parser (provider buf)
+  fun buf ->
+    let provider () =
+      let tok = Lexer.token buf in
+      let start, stop = Sedlexing.lexing_positions buf in
+      (tok, start, stop)
+    in
+    try Ok (parser provider) with
+    | Menhir_parser.Error -> Error "parser error"
+    | Lexer.Error -> Error "lexer error"
 
-let parse buf =
-  try Ok (parser_result buf) with
-  | Menhir_parser.Error -> Error "parser error"
-  | Lexer.Error -> Error "lexer error"
+(** Parse a config from a string. *)
+let from_string s = from_lexbuf (Sedlexing.Utf8.from_string s)
 
-let from_string s = parse (Sedlexing.Utf8.from_string s)
-
-let from_channel c = parse (Sedlexing.Utf8.from_channel c)
+(** Parse a config from a channel. *)
+let from_channel c = from_lexbuf (Sedlexing.Utf8.from_channel c)
 
+(** Parse a config from a file. *)
 let from_file f =
   let chan = open_in f in
-  let result = parse (Sedlexing.Utf8.from_channel chan) in
+  let result = from_lexbuf (Sedlexing.Utf8.from_channel chan) in
   close_in chan;
   result

src/pp.ml

@@ -1,10 +1,20 @@
+(** Module providing functions to pretty print a config or parts of a config. *)
+
 open Types
 
+(** The string used to print one level of indentation. Defaults to two spaces. *)
 let indent_s = ref "  "
 
+(**/**)
+
+(** Print a given number of level indentation. *)
 let rec indent fmt n =
   if n = 0 then () else Format.fprintf fmt "%s%a" !indent_s indent (n - 1)
 
+(**/**)
+
+(** Print a name or a parameter on a given formatter. The function will try to
+    print with as low quoting as possible. *)
 let param =
   let chars_to_quote = Hashtbl.create 512 in
   Array.iter
@@ -31,6 +41,7 @@ let param =
     end
     else Format.fprintf fmt "%s" param
 
+(** Print a list of parameters on a given formatter. *)
 let params fmt = function
   | [] -> ()
   | params ->
@@ -40,23 +51,30 @@ let params fmt = function
          param )
       params
 
-let rec children n fmt = function
+(** Print children of a directive on a given formatter. *)
+let rec children n fmt (children : Types.directive list) =
+  match children with
   | [] -> ()
   | children ->
     Format.fprintf fmt " {@.%a@.%a}" (config n) children indent (max 0 (n - 1))
 
+(** Print a directive on a given formatter. *)
 and directive n fmt d =
   Format.fprintf fmt {|%a%a%a%a|} indent n param d.name params d.params
     (children (n + 1))
     d.children
 
-and config n fmt config =
+(** Print a config on a given formatter. *)
+and config n fmt (config : Types.config) =
   Format.pp_print_list
     ~pp_sep:(fun fmt () -> Format.fprintf fmt "@.%a" indent (max 0 (n - 2)))
     (directive n) fmt config
 
+(** Print children of a directive on a given formatter. *)
 let children = children 0
 
+(** Print a directive on a given formatter. *)
 let directive = directive 0
 
+(** Print a config on a given formatter. *)
 let config = config 0

src/scfg.ml

@@ -5,9 +5,8 @@ let error msg =
   exit 1
 
 let () =
-  let argc = Array.length Sys.argv in
-
-  if argc <> 2 then error (Format.sprintf "usage: %s <file>" Sys.argv.(0));
+  if Array.length Sys.argv <> 2 then
+    error (Format.sprintf "usage: %s <file>" Sys.argv.(0));
 
   let file = Sys.argv.(1) in
 

src/types.ml

@@ -1,7 +1,11 @@
+(** Module defining types used to represent a config. *)
+
+(** A directive has a name, a list of parameters and a list of children. *)
 type directive =
   { name : string
   ; params : string list
   ; children : directive list
   }
 
+(** A config is a list of directives. *)
 type config = directive list