Document Cobol_parser.Parser_engine

src/lsp/cobol_parser/parser_engine.mli

@@ -16,41 +16,85 @@ open Parser_outputs
 
 (** {1 Basic (one-shot) parsing} *)
 
+(** Simple 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:
+
+    - a simple parse-tree [Some (Only ptree)] in case the parser managed to
+      make some sense of the inputs;
+
+    - a parse-tree along with some artifacts
+      [Some (WithArtifacts (ptree, artifacts))];
+
+    - no result at all [None].
+
+    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 result is not [None] 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. *)
 type 'm simple_parsing
   = ?options:Parser_options.parser_options
   -> ?config:Cobol_config.t
   -> Cobol_preproc.preprocessor
   -> (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 postion.  To this end, their results include a
+    {!rewinder}  *)
 type 'm rewindable_parsing
   = ?options:parser_options
   -> ?config:Cobol_config.t
   -> Cobol_preproc.preprocessor
   -> (((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