diff --git a/src/menhir.ml b/src/menhir.ml
index 66d31eb1..710111bf 100644
--- a/src/menhir.ml
+++ b/src/menhir.ml
@@ -2,33 +2,56 @@ open Import
 open Build.O
 open! No_io
 
+module SC = Super_context
+
+(* - [sctx]: super context. Stores all the informations about the
+   current build context. The current compiler can be obtained via:
+
+   {[
+     (SC.context sctx).ocamlc
+   ]}
+
+   - [dir]: directory inside [_build/<context>/...] where the build happens.
+   If the [(menhir ...)] appears in [src/jbuild], then [dir] is of the form
+   [_build/<context>/src], for instance [_build/default/src].
+
+   - [scope]: represent the scope this stanza is part of. Jbuilder allows to
+   build multiple projects at once and splits the source tree into one
+   scope per project
+
+   - [t]: the parsed [(menhir ...)] stanza
+*)
 let gen_rules sctx ~dir ~scope (t : Jbuild.Menhir.t) =
   let targets n = List.map ~f:(Path.relative dir) [n ^ ".ml"; n ^ ".mli"] in
-  let flags =
-    Super_context.expand_and_eval_set sctx ~scope ~dir t.flags
-      ~standard:[] in
-  let menhir =
-    let menhir =
-      Super_context.resolve_program sctx ~hint:"opam install menhir" "menhir" in
-    fun ~extra_targets args->
-      flags
-      >>> (Build.run ~extra_targets
-             menhir
-             ~dir
-             ~context:(Super_context.context sctx)
-             args) in
+  (* This expands special variables such as ${ROOT} in the flags *)
+  let flags = SC.expand_and_eval_set sctx ~scope ~dir t.flags ~standard:[] in
+  let menhir_binary =
+    SC.resolve_program sctx "menhir" ~hint:"opam install menhir"
+  in
+  (* [extra_targets] is to tell Jbuilder about generated files that do
+     not appear in the menhir command line. *)
+  let menhir ~extra_targets args =
+    flags
+    >>>
+    Build.run ~extra_targets
+      menhir_binary
+      ~dir
+      ~context:(SC.context sctx)
+      args
+  in
   let add_rule_get_targets =
-    Super_context.add_rule_get_targets sctx ~mode:t.mode ~loc:t.loc in
+    SC.add_rule_get_targets sctx ~mode:t.mode ~loc:t.loc
+  in
   let mly name = Path.relative dir (name ^ ".mly") in
   match t.merge_into with
   | None ->
-    List.concat_map ~f:(fun name ->
+    List.concat_map t.modules ~f:(fun name ->
       add_rule_get_targets (
         menhir
           ~extra_targets:(targets name)
           [ Dyn (fun x -> As x)
-          ; Dep (mly name)]
-      )) t.modules
+          ; Dep (mly name)
+          ]))
   | Some merge_into ->
     add_rule_get_targets (
       menhir
diff --git a/src/menhir.mli b/src/menhir.mli
index 8ad2f850..0699ed1d 100644
--- a/src/menhir.mli
+++ b/src/menhir.mli
@@ -1,4 +1,9 @@
+(** Menhir rules *)
 
+(** Generate the rules for a [(menhir ...)] stanza. Return the list of
+    targets that are generated by these rules. This list of targets is
+    used by the code that computes the list of modules in the
+    directory. *)
 val gen_rules
   :  Super_context.t
   -> dir:Path.t