From c1871e9f355830062f67429ae05f6dbda73ba8c5 Mon Sep 17 00:00:00 2001
From: Simon Cruanes <simon.cruanes.2007@m4x.org>
Date: Tue, 22 Sep 2015 22:50:02 +0200
Subject: [PATCH] doc

---
 src/string/CCParse.mli | 125 +++++++++++++++++++++++++++++++++--------
 1 file changed, 103 insertions(+), 22 deletions(-)

diff --git a/src/string/CCParse.mli b/src/string/CCParse.mli
index 363e45a2..bb9cddfd 100644
--- a/src/string/CCParse.mli
+++ b/src/string/CCParse.mli
@@ -94,47 +94,112 @@ val input_of_chan : ?size:int -> in_channel -> input
 type 'a t = input -> 'a (** @raise ParseError in case of failure *)
 
 val return : 'a -> 'a t
-val pure : 'a -> 'a t (** synonym to {!return} *)
+(** Always succeeds, without consuming its input *)
+
+val pure : 'a -> 'a t
+(** synonym to {!return} *)
+
 val (>|=) : 'a t -> ('a -> 'b) -> 'b t
+(** Map *)
+
 val (>>=) : 'a t -> ('a -> 'b t) -> 'b t
+(** Monadic bind *)
+
 val (<*>) : ('a -> 'b) t -> 'a t -> 'b t
+(** Applicative *)
+
 val (<* ) : 'a t -> _ t -> 'a t
+(** [a <* b] parses [a] into [x], parses [b] and ignores its result,
+    and returns [x] *)
+
 val ( *>) : _ t -> 'a t -> 'a t
+(** [a *> b] parses [a], then parses [b] into [x], and returns [x]. The
+    results of [a] is ignored. *)
 
 val fail : string -> 'a t
-val eoi : unit t (** end of string *)
-val nop : unit t (** do nothing *)
+(** [fail msg] fails with the given message. It can trigger a backtrack *)
+
+val eoi : unit t
+(** Expect the end of input, fails otherwise *)
+
+val nop : unit t
+(** Succeed with [()] *)
 
 val char : char -> char t
-val char_if : (char -> bool) -> char t
-val chars_if : (char -> bool) -> string t
-val chars1_if : (char -> bool) -> string t (** non empty *)
-val endline : char t
-val space : char t (** tab or space *)
-val white : char t (** tab or space or newline *)
+(** [char c] parses the char [c] and nothing else *)
+
+val char_if : (char -> bool) -> char t
+(** [char_if f] parses a character [c] if [f c = true] *)
+
+val chars_if : (char -> bool) -> string t
+(** [chars_if f] parses a string of chars that satisfy [f] *)
+
+val chars1_if : (char -> bool) -> string t
+(** Same as {!chars_if}, but only non-empty strings *)
+
+val endline : char t
+(** Parses '\n' *)
+
+val space : char t
+(** tab or space *)
+
+val white : char t
+(** tab or space or newline *)
+
+val skip_chars : (char -> bool) -> unit t
+(** Skip 0 or more chars satisfying the predicate *)
 
-val skip_chars : (char -> bool) -> unit t (** Skip 0 or more chars *)
 val skip_space : unit t
+(** Skip ' ' and '\t' *)
+
 val skip_white : unit t
+(** Skip ' ' and '\t' and '\n' *)
 
 val is_alpha : char -> bool
-val is_num : char -> bool
-val is_alpha_num : char -> bool
-val is_space : char -> bool
-val (~~~) : (char -> bool) -> char -> bool
-val (|||) : (char -> bool) -> (char -> bool) -> char -> bool
-val (&&&) : (char -> bool) -> (char -> bool) -> char -> bool
+(** Is the char a letter? *)
 
-val (<|>) : 'a t -> 'a t -> 'a t  (* succeeds if either succeeds *)
+val is_num : char -> bool
+(** Is the char a digit? *)
+
+val is_alpha_num : char -> bool
+
+val is_space : char -> bool
+(** True on ' ' and '\t' *)
+
+val is_white : char -> bool
+(** True on ' ' and '\t' and '\n'
+    @since NEXT_RELEASE *)
+
+val (~~~) : (char -> bool) -> char -> bool
+(** Negation on predicates *)
+
+val (|||) : (char -> bool) -> (char -> bool) -> char -> bool
+(** Disjunction on predicates *)
+
+val (&&&) : (char -> bool) -> (char -> bool) -> char -> bool
+(** Conjunction on predicates *)
+
+val (<|>) : 'a t -> 'a t -> 'a t
+(** [a <|> b] tries to parse [a], and if [a] fails, backtracks and tries
+    to parse [b]. Therefore, it succeeds if either succeeds *)
 
 val string : string -> string t
+(** [string s] parses exactly the string [s], and nothing else *)
 
 val many : 'a t -> 'a list t
-val many1 : 'a t -> 'a list t (** non empty *)
+(** [many p] parses a list of [p], eagerly (as long as possible) *)
+
+val many1 : 'a t -> 'a list t
+(** parses a non empty list *)
+
 val skip : _ t -> unit t
+(** [skip p] parses [p] and ignores its result *)
 
 val sep : by:_ t -> 'a t -> 'a list t
-val sep1 : by:_ t -> 'a t -> 'a list t (** non empty *)
+(** [sep ~by p] parses a list of [p] separated by [by] *)
+
+val sep1 : by:_ t -> 'a t -> 'a list t
+(** [sep1 ~by p] parses a non empty list of [p], separated by [by] *)
 
 val fix : ('a t -> 'a t) -> 'a t
 (** Fixpoint combinator *)
@@ -142,10 +207,17 @@ val fix : ('a t -> 'a t) -> 'a t
 (** {2 Parse} *)
 
 val parse : input:input -> 'a t -> 'a or_error
-val parse_exn : input:input -> 'a t -> 'a (** @raise ParseError if it fails *)
+(** [parse ~input p] applies [p] on the input, and returns [`Ok x] if
+    [p] succeeds with [x], or [`Error s] otherwise *)
+
+val parse_exn : input:input -> 'a t -> 'a
+(** @raise ParseError if it fails *)
 
 val parse_string : string -> 'a t -> 'a or_error
-val parse_string_exn : string -> 'a t -> 'a (** @raise ParseError if it fails *)
+(** Specialization of {!parse} for string inputs *)
+
+val parse_string_exn : string -> 'a t -> 'a
+(** @raise ParseError if it fails *)
 
 val parse_file : ?size:int -> file:string -> 'a t -> 'a or_error
 (** [parse_file ~file p] parses [file] with [p] by opening the file
@@ -161,9 +233,18 @@ val parse_file_exn : ?size:int -> file:string -> 'a t -> 'a
 
 module U : sig
   val list : ?start:string -> ?stop:string -> ?sep:string -> 'a t -> 'a list t
+  (** [list p] parses a list of [p], with the OCaml conventions for
+      start token "[", stop token "]" and separator ";".
+      Whitespace between items are skipped *)
+
   val int : int t
-  val word : string t (** alpha num, start with alpha *)
+
+  val word : string t
+  (** non empty string of alpha num, start with alpha *)
+
   val map : ('a -> 'b) -> 'a t -> 'b t
+
   val map2 : ('a -> 'b -> 'c) -> 'a t -> 'b t -> 'c t
+
   val map3 : ('a -> 'b -> 'c -> 'd) -> 'a t -> 'b t -> 'c t -> 'd t
 end