comments translation: outline_parser.mli

outline_utils.mli

@@ -1,68 +1,69 @@
 (** {0 Outline parser}
-  * Définititions auxiliaires utilisées par le parser d'outline *)
+ * Auxiliary definitions used by the outline parser *)
 
 type offset = History.offset
 type position = Lexing.position
 
-(** Les constructions du code source sont découpées en "chunk" de différentes
-  * kinds. *)
+(** Source code constructs are split into "chunks" of different "kinds". *)
 type kind =
   | Enter_module (* module _ = struct *)
   | Leave_module (* end *)
   | Definition   (* let / type / … *)
-  | Rollback     (* and … : nous devons retourner à la définition précédente
-                  *         pour retrouver le /genre/ de définition *)
-  | Done         (* EOF rencontré après une construction syntaxiquement correcte *)
-  | Unterminated (* La construction syntaxique n'est pas terminée *)
+  | Rollback     (* and … : we should go back to the previous definition
+                  * to find its "kind" *)
+  | Done         (* EOF found after a syntactically correct construction *)
+  | Unterminated (* Unfinished syntactic construction *)
   | Syntax_error of Location.t
-  | Exception of exn (* Une exception est survenue dans le parser, à traiter en amont *)
+  | Exception of exn (* The parser raised an exception,
+                      * to be handled by the caller *)
 
-(** Le parser d'outline fonctionne par effet de bord :
-  * - en général, les productions n'ont aucune action sémantique
-  * - quand le parser rencontre une construction syntaxique qu'il sait délimiter
-  *   (ci-dessus: module ou définition), il lève l'exception Chunk.
-  * La position renvoyée est celle du dernier token du chunk, afin de distinguer
-  * l'éventuel token lookahead consommé par le parser et de le rajouter en début
-  * du lexing buffer.
+(** The outline parser proceeds by side-effects:
+  * - most productions have no attached semantic action
+  * - when the parser finds a syntactic construct that it knows how to chunk
+  *   (above: module or definition), it raises the [Chunk] exception.
+  * The associated position is the position of the last token of the
+  * chunk, so that, if the parser consumed a lookahead token, it can
+  * be recognized and added back to the lexing buffer.
   * EX: let a = 5 type t = ...
   *                  ^ |CHUNK: let a = 5|
-  * Le parser ne lève Chunk qu'après type, il faut réajouter le token type en
-  * début de flux.
+  *   The parser raises [Chunk] only after [type], so we must add the
+  *   [type] token back to the input stream.
   *)
 exception Chunk of kind * position
 
-(** Si !filter_first > 0, le parser ne lève pas d'exception mais décrémente
-  * filter_first. Cela permet d'implanter le rollback quand le code source est
-  * donné en plusieurs fois.
-  * Ainsi "let x = 5" puis "and y = 6" est analysée en :
+(** If [!filter_first > 0], the parser will not raise an exception but
+  * decrement [filter_first]. This allows to implement rollback when
+  * a source code is feed in several separate commands.
+  * For example "let x = 5" then "and y = 6" are analyzed as :
   * - "let x = 5" : raise Chunk (Definition,_)
   * - "and …" : raise Chunk (Rollback,_)
   * - filter_first := 1
-  * - "let x = 5 and y = 6" : raise Chunk(Definition,_)
-  * -            ^ une exception Chunk(Definition) est ignorée ici
-  *                et filter_first décrémenté
+  *   "let x = 5 and y = 6" : raise Chunk(Definition,_)
+  *              ^ no Chunk(Definition) is raised here and
+  *                filter_first is decremented
   *)
 val filter_first : int ref
 
-(** Utilisé pour ignorer les modules de première classe :
-  * la construction :
-  * "let module = … in " permet de définir un module à l'intérieur d'une
-  * définition, mais le parser d'outline ne sait pas interrompre une définition
-  * (elle est soit complètement correcte, soit complètement fausse).
-  * À chaque entrée dans ce genre de définition nesting est incrémenté, à la
-  * sortie nesting est décrémenté. Une définition de module est reportée
-  * uniquement si !nesting = 0.
+(** Used to ignore first-class modules.
+  * The construct "let module = … in " allows to define a module
+  * locally inside a definition, but our outline parser cannot work
+  * inside a definition (it is either correct as a whole,
+  * or incorrect).
+  * [nesting] is incremented at the beginning of such constructions
+  * (here, [let module]) and decremented at its end (here, after the
+  * module expression is parsed).No module definition is reported
+  * while [!nesting > 0].
   *) 
 val nesting : int ref
 
-(** Appelé pour initialiser le parser avant chaque parser.
+(** Called to (re)initialize the parser.
   * filter_first := rollback; nesting := 0
   *)
 val reset : rollback:int -> unit -> unit
 
-(** Augmente nesting *)
+(** Increments [nesting] *)
 val enter_sub : unit -> unit
-(** Décrémente nesting *)
+(** Decrements [nesting] *)
 val leave_sub : unit -> unit
-(** Lève l'exception si !nesting = 0 et !filter_first = 0 *)
+(** Sends [Chunk] only when [!nesting] is 0 and [!filter_first] is 0 *)
 val emit_top : kind -> position -> unit