From 967b0586441c7e1c956e6e3b3f70249e821831d0 Mon Sep 17 00:00:00 2001
From: Nicolas Berthier <nicolas.berthier@ocamlpro.com>
Date: Tue, 3 Oct 2023 16:22:38 +0200
Subject: [PATCH] Document `Cobol_parser.Parser_engine`

---
 src/lsp/cobol_parser/parser_engine.mli | 53 +++++++++++++++++++++++---
 1 file changed, 48 insertions(+), 5 deletions(-)

diff --git a/src/lsp/cobol_parser/parser_engine.mli b/src/lsp/cobol_parser/parser_engine.mli
index 60cdcedb8..bd207ebb2 100644
--- a/src/lsp/cobol_parser/parser_engine.mli
+++ b/src/lsp/cobol_parser/parser_engine.mli
@@ -14,8 +14,27 @@
 open Parser_options
 open Parser_outputs
 
+(** Parsing functions essentially parse a stream of tokens that is produced by a
+    given preprocessor (typically returned by
+    {!val:Cobol_preproc.preprocessor}).  The result always consists in a
+    (possibly empty) set of diagnostics, along with either:
+
+    - an optional parse-tree [Only (Some ptree)] only;
+
+    - an optional parse-tree along with some artifacts
+      [WithArtifacts (Some ptree, artifacts)].
+
+    The set of diagnostics attached to the result of parsing functions
+    ([result.diags]) should {e always} be checked for errors upon return ({i
+    i.e,} {!Cobol_common.Diagnostics.Set.has_errors} holds).  This is in
+    particular the case when the resulting parse-tree is provided and recovery
+    is enabled ([options.recovery <> DisableRecovery]), as in such a case, the
+    parse-tree returned may contain dummy nodes and source locations produced
+    using the recovery mechanism. *)
+
 (** {1 Basic (one-shot) parsing} *)
 
+(** Simple parsing functions traverse the inputs once to produce a result. *)
 type 'm simple_parsing
   = ?options:Parser_options.parser_options
   -> ?config:Cobol_config.t
@@ -23,15 +42,23 @@ type 'm simple_parsing
   -> (PTree.compilation_group option, 'm) output
     Cobol_common.Diagnostics.with_diags
 
-val parse
-  : memory: 'm memory -> 'm simple_parsing
+(* val parse *)
+(*   : memory: 'm memory -> 'm simple_parsing *)
+
+(** Simple parsing function that does not return any artifact. *)
 val parse_simple
   : Cobol_common.Behaviors.amnesic simple_parsing
+
+(** Simple parsing function does return some artifacts. *)
 val parse_with_artifacts
   : Cobol_common.Behaviors.eidetic simple_parsing
 
 (** {1 Rewindable parsing} *)
 
+(** Rewindable parsing functions extend the behaviors of simple parsing
+    functions, with the ability to {i rewind} the parser (and pre-processor)
+    before a given lexing position.  To this end, their results include a
+    {!rewinder} that may then be given to {!rewind_and_parse}. *)
 type 'm rewindable_parsing
   = ?options:parser_options
   -> ?config:Cobol_config.t
@@ -39,18 +66,34 @@ type 'm rewindable_parsing
   -> (((PTree.compilation_group option, 'm) output as 'x) *
       'x rewinder)
     Cobol_common.Diagnostics.with_diags
+
+(** Rewinder for parsing functions that produce results of type ['x] *)
 and 'x rewinder
+
+(** Functions for rewinding the pre-processor.  Such a function should return a
+    preprocessor in the {e exact same state} as the one given in argument, with
+    the only exception that the input text is now read from [new_position].  If
+    [new_position] is not given, the text should be read from the very begining
+    of the input. *)
 and preprocessor_rewind =
   ?new_position:Lexing.position -> (Cobol_preproc.preprocessor as 'r) -> 'r
 
-val rewindable_parse
-  : memory:'m memory
-  -> 'm rewindable_parsing
+(* val rewindable_parse *)
+(*   : memory:'m memory -> 'm rewindable_parsing *)
+
+(** Rewindable parsing function that does not return any artifact. *)
 val rewindable_parse_simple
   : Cobol_common.Behaviors.amnesic rewindable_parsing
+
+(** Rewindable parsing function that does return some artifacts. *)
 val rewindable_parse_with_artifacts
   : Cobol_common.Behaviors.eidetic rewindable_parsing
 
+(** [rewind_and_parse rewinder preprocessor_rewind ~position] uses [rewinder] to
+    restart parsing before the given [position].  Note that the [new_position]
+    argument that is given to [preprocessor_rewind] may often {e not} correspond
+    to [position] ({i i.e,} the parser may need to rewind earlier than
+    [position]). *)
 val rewind_and_parse
   : 'x rewinder
   -> preprocessor_rewind