[minor] documentation improvements for Makefile.menhir

Makefile

@@ -1050,8 +1050,29 @@ clean::
 # In order to avoid a build-time dependency on Menhir,
 # we store the result of the parser generator (which
 # are OCaml source files) and Menhir's runtime libraries
-# (that the parser files rely on) in boot/
+# (that the parser files rely on) in boot/.
 
+# The rules below do not depend on Menhir being available,
+# they just build the parser from the boot/.
+
+# See Makefile.menhir for the rules to rebuild the parser and update
+# boot/, which require Menhir. The targets in Makefile.menhir
+# (also included here for convenience) must be used after any
+# modification of parser.mly.
+include Makefile.menhir
+
+# To avoid module-name conflicts with compiler-lib users that link
+# with their code with their own MenhirLib module (possibly with
+# a different Menhir version), we rename MenhirLib into
+# CamlinternalMenhirlib -- and replace the module occurrences in the
+# generated parser.ml.
+
+parsing/camlinternalMenhirLib.ml: boot/menhir/menhirLib.ml
+	cp $< $@
+parsing/camlinternalMenhirLib.mli: boot/menhir/menhirLib.mli
+	cp $< $@
+
+# Copy parsing/parser.ml from boot/
 parsing/parser.ml: \
   boot/menhir/parser.ml parsing/parser.mly
 	@if [ -n "$(shell find parsing/parser.mly \
@@ -1070,22 +1091,9 @@ parsing/parser.ml: \
 parsing/parser.mli: boot/menhir/parser.mli
 	cat $< | sed "s/MenhirLib/CamlinternalMenhirLib/g" > $@
 
-# We rename the menhirLib module into CamlinternalMenhirlib,
-# to avoid module-name conflicts with compiler-libs users
-# also linking their own MenhirLib module for another parser.
-parsing/camlinternalMenhirLib.ml: boot/menhir/menhirLib.ml
-	cp $< $@
-parsing/camlinternalMenhirLib.mli: boot/menhir/menhirLib.mli
-	cp $< $@
-
-# Makefile.menhir exports an promote-menhir rule that calls Menhir on
-# the current grammar and refreshes the boot/ files. It must be called
-# for any modification of the grammar to be taken into account by the
-# compiler.
-include Makefile.menhir
-
 partialclean:: partialclean-menhir
 
+
 # OCamldoc
 
 .PHONY: ocamldoc

Makefile.menhir

@@ -13,8 +13,37 @@
 #*                                                                        *
 #**************************************************************************
 
+# The rules in this Makefile use Menhir to rebuild the OCaml compiler
+# parser. They are include in the main Makefile, so should be invoked
+# directly, for example 'make promote-menhir'. They must be called
+# after any modification to parsing/parser.mly, for the modification
+# to affect the parser linked in the produced compiler:
+#
+# - promote-menhir builds the parser from parser.mly and stores it in
+#   the boot/ directory, so that future builds of the compiler use the
+#   updated result. Use it to make permanent changes to the compiler
+#   parser.
+#
+# - test-menhir builds the parser from parser.mly without storing it
+#   in the boot/ directory, and only checks that the generated parser
+#   builds correctly. Use it to quickly check if a parser.mly change
+#   breaks the build. If you want to test a compiler produced with
+#   the new parser, you must use promote-menhir instead.
+#   (Using this rule requires a partial compiler build as obtained
+#    by 'make core' or 'make world'.)
+#
+# - clean-menhir removes the files generated by Menhir from parsing/,
+#   keeping only the reference sources for the grammar.
+#
+# - depend-menhir updates the dependency information for the
+#   Menhir-generated parser, which is versioned in the OCaml repository
+#   like all other .depend files. It should be used when the dependencies
+#   (of the OCaml code in the grammar semantic actions) change.
+
 MENHIR ?= menhir
 
+## Menhir compilation flags
+
 MENHIRFLAGS := --explain --ocamlc "$(CAMLC) $(COMPFLAGS)" --infer\
 	--lalr --strict --table \
         --unused-token COMMENT --unused-token DOCSTRING --unused-token EOL\
@@ -27,37 +56,63 @@ MENHIRFLAGS := --explain --ocamlc "$(CAMLC) $(COMPFLAGS)" --infer\
 # (which is used in polymorphic variant), but is not currently used by
 # the grammar.
 
-.PHONY: import-menhirLib
 
+## promote-menhir
+
+.PHONY: promote-menhir
+promote-menhir: parsing/parser.mly
+	$(MAKE) import-menhirLib
+	$(MENHIR) $(MENHIRFLAGS) parsing/parser.mly
+	cp $(addprefix parsing/parser.,ml mli) boot/menhir
+
+# The import-menhirLib invocation in promote-menhir ensures that each
+# update of the boot/ parser is paired with an update of the imported
+# menhirLib; otherwise it would be easy to generate a parser and keep
+# an incompatible version of menhirLib, which would fail at
+# compile-time.
+
+.PHONY: import-menhirLib
 import-menhirLib:
 	mkdir -p boot/menhir
 	cp \
            $(addprefix `$(MENHIR) --suggest-menhirLib`/menhirLib.,ml mli) \
            boot/menhir
 
-# The import-menhirLib invocation ensures that each call to $(MENHIR)
-# is paired with an update of the imported menhirLib; otherwise it
-# would be easy to generate a parser and keep an incompatible version of
-# menhirLib, which would fail at compile-time.
-promote-menhir: parsing/parser.mly
-	$(MAKE) import-menhirLib
-	$(MENHIR) $(MENHIRFLAGS) parsing/parser.mly
-	cp $(addprefix parsing/parser.,ml mli) boot/menhir
 
+## test-menhir
+
+# This rule assumes that the `parsing/` sources and its dependencies
+# have already been compiled; 'make core' suffices to be in that
+# state. We don't make 'core' an explicit dependency, as building
+# 'test-menhir' repeatedly would rebuild the compiler each time
+# (parser.ml has changed), without actually taking the changes from
+# parser.mly into account ('core' uses the parser from boot/).
+
+# The test-menhir target does not read or write the boot directory,
+# it directly builds the parser in parsing/. In particular, it must
+# duplicate the MenhirLib->CamlinternalMenhirlib renaming usually
+# performed by the parsing/parser.ml import rule in the main
+# Makefile.
 .PHONY: test-menhir
 test-menhir: parsing/parser.mly
 	$(MENHIR) $(MENHIRFLAGS) parsing/parser.mly
 	sed -i "s/MenhirLib/CamlinternalMenhirLib/g" \
 	  $(addprefix parsing/parser.,ml mli)
 	$(MAKE) parsing/parser.cmo
 
+
+## clean-menhir
+
 partialclean-menhir::
 	rm -f \
 	  $(addprefix parsing/parser.,ml mli) \
 	  $(addprefix parsing/camlinternalMenhirLib.,ml mli)
 
 clean-menhir: partialclean-menhir
 
+
+## depend-menhir
+
 .PHONY: depend-menhir
 depend-menhir:
 	$(MENHIR) --depend --ocamldep "$(CAMLDEP) -slash $(DEPFLAGS)" \