MPR7546, manual: preambles and warnings for compiler-libs modules (ocaml#2020)

Octachron · web-flow · commit ef135a71ae1e · 2018-09-12T09:51:47.000+02:00
* preambles for compiler-libs modules

* Compilerlibs intro and warning link
diff --git a/Changes b/Changes
@@ -245,6 +245,10 @@ Working version
 
 ### Manual and documentation:
 
+- MPR#7546, GPR#2020: preambles and introduction for compiler-libs.
+  (Florian Angeletti, review by Daniel Bünzli, Perry E. Metzger
+  and Gabriel Scherer)
+
 - MPR#7825: html manual split compilerlibs from stdlib in the html
   index of modules
   (Florian Angeletti, review by Perry E. Metzger and Gabriel Scherer)
diff --git a/bytecomp/simplif.mli b/bytecomp/simplif.mli
@@ -13,7 +13,12 @@
 (*                                                                        *)
 (**************************************************************************)
 
-(** Lambda simplification and lambda plugin hooks *)
+(** Lambda simplification and lambda plugin hooks
+
+  {b Warning:} this module is unstable and part of
+  {{!Compiler-libs}compiler-libs}.
+
+*)
 
 (* Elimination of useless Llet(Alias) bindings.
    Transformation of let-bound references into variables.
diff --git a/driver/pparse.mli b/driver/pparse.mli
@@ -13,7 +13,12 @@
 (*                                                                        *)
 (**************************************************************************)
 
-(** Driver for the parser, external preprocessors and ast plugin hooks *)
+(** Driver for the parser, external preprocessors and ast plugin hooks
+
+  {b Warning:} this module is unstable and part of
+  {{!Compiler-libs}compiler-libs}.
+
+*)
 
 open Format
 
diff --git a/manual/manual/Makefile b/manual/manual/Makefile
@@ -57,13 +57,22 @@ htmlman/libref/style.css: style.css $(STDLIB_MLIS)
 	  $(STDLIB_MLIS)
 	cp style.css $@
 
+COMPILERLIBS_MODULES=$(shell echo $(basename $(notdir $(COMPILERLIBS_MLIS))) \
+| sed "s/\<./\U&/g")
 
-htmlman/compilerlibref/style.css: style.css $(COMPILERLIBS_MLIS)
+library/compiler-libs.txt: library/compiler-libs.mld
+	cp $< $@ && echo "{!modules:$(COMPILERLIBS_MODULES)}" >> $@
+
+
+htmlman/compilerlibref/style.css: library/compiler-libs.txt style.css \
+  $(COMPILERLIBS_MLIS)
 	mkdir -p htmlman/compilerlibref
 	$(OCAMLDOC) -colorize-code -sort -html \
 	  -d htmlman/compilerlibref \
 	  -I $(SRC)/stdlib \
 	  $(DOC_COMPILERLIBS_INCLUDES) \
+          -intro library/compiler-libs.txt \
+          library/compiler-libs.txt \
 	  $(COMPILERLIBS_MLIS)
 	cp style.css $@
 
@@ -153,6 +162,7 @@ clean:
 	$(MAKE) -C refman    clean
 	$(MAKE) -C tutorials clean
 	-rm -f texstuff/*
-	cd htmlman; rm -rf libref index.html manual*.html *.haux *.hind *.svg
+	cd htmlman; rm -rf libref compilerlibref index.html \
+	manual*.html *.haux *.hind *.svg
 	cd textman; rm -f manual.txt *.haux *.hind
 	cd infoman; rm -f ocaml.info ocaml.info-*  *.haux *.hind
diff --git a/manual/manual/library/.gitignore b/manual/manual/library/.gitignore
@@ -3,3 +3,5 @@
 arithstatus.mli
 ocamldoc.out
 ocamldoc.sty
+compiler-libs.txt
+
diff --git a/manual/manual/library/Makefile b/manual/manual/library/Makefile
@@ -74,3 +74,4 @@ ocamldoc.out: $(DOC_ALL_MLIS)
 .PHONY: clean
 clean:
 	rm -f *.tex ocamldoc.out ocamldoc.sty
+	rm -f compiler-libs.txt
diff --git a/manual/manual/library/compiler-libs.mld b/manual/manual/library/compiler-libs.mld
@@ -0,0 +1,9 @@
+{!indexlist}
+
+{1 Warning}
+  This library is part of the internal OCaml compiler API, and is
+not the language standard library.
+  There are no compatibility guarantees between releases, so code written
+against these modules must be willing to depend on specific OCaml compiler
+versions.
+
diff --git a/ocamldoc/Makefile b/ocamldoc/Makefile
@@ -399,14 +399,18 @@ stdlib_man/Stdlib.3o: $(OCAMLDOC) $(DOC_ALL_MLIS)
 	$(OCAMLDOC_RUN) -man -d stdlib_man -nostdlib \
 	-hide Stdlib -lib Stdlib $(DOC_ALL_INCLUDES) \
 	-pp "$(AWK) -v ocamldoc=true -f $(SRC)/stdlib/expand_module_aliases.awk" \
-	-t "OCaml library" -man-mini $(DOC_ALL_MLIS)
+	-t "OCaml library" -man-mini \
+	-text $(SRC)/manual/manual/library/compiler-libs.mld \
+	$(DOC_ALL_MLIS)
 
 stdlib_html/Stdlib.html: $(OCAMLDOC) $(DOC_ALL_MLIS)
 	$(MKDIR) stdlib_html
 	$(OCAMLDOC_RUN) -html -d stdlib_html -nostdlib \
 	-hide Stdlib -lib Stdlib $(DOC_ALL_INCLUDES) \
 	-pp "$(AWK) -v ocamldoc=true -f $(SRC)/stdlib/expand_module_aliases.awk" \
-	-t "OCaml library" $(DOC_ALL_MLIS)
+	-t "OCaml library" \
+	-text $(SRC)/manual/manual/library/compiler-libs.mld \
+	$(DOC_ALL_MLIS)
 
 .PHONY: autotest_stdlib
 autotest_stdlib:
diff --git a/parsing/ast_helper.mli b/parsing/ast_helper.mli
@@ -13,7 +13,12 @@
 (*                                                                        *)
 (**************************************************************************)
 
-(** Helpers to produce Parsetree fragments *)
+(** Helpers to produce Parsetree fragments
+
+  {b Warning} This module is unstable and part of
+  {{!Compiler-libs}compiler-libs}.
+
+*)
 
 open Asttypes
 open Docstrings
diff --git a/parsing/ast_invariants.mli b/parsing/ast_invariants.mli
@@ -12,7 +12,12 @@
 (*                                                                        *)
 (**************************************************************************)
 
-(** Check AST invariants *)
+(** Check AST invariants
+
+  {b Warning:} this module is unstable and part of
+  {{!Compiler-libs}compiler-libs}.
+
+*)
 
 val structure : Parsetree.structure -> unit
 val signature : Parsetree.signature -> unit
diff --git a/parsing/ast_iterator.mli b/parsing/ast_iterator.mli
@@ -15,7 +15,12 @@
 
 (** {!iterator} allows to implement AST inspection using open recursion.  A
     typical mapper would be based on {!default_iterator}, a trivial iterator,
-    and will fall back on it for handling the syntax it does not modify. *)
+    and will fall back on it for handling the syntax it does not modify.
+
+  {b Warning:} this module is unstable and part of
+  {{!Compiler-libs}compiler-libs}.
+
+*)
 
 open Parsetree
 
diff --git a/parsing/ast_mapper.mli b/parsing/ast_mapper.mli
@@ -46,6 +46,9 @@ let () =
   the constant [42], can be compiled using
   [ocamlc -o ppx_test -I +compiler-libs ocamlcommon.cma ppx_test.ml].
 
+  {b Warning:} this module is unstable and part of
+  {{!Compiler-libs}compiler-libs}.
+
   *)
 
 open Parsetree
diff --git a/parsing/asttypes.mli b/parsing/asttypes.mli
@@ -13,7 +13,12 @@
 (*                                                                        *)
 (**************************************************************************)
 
-(** Auxiliary AST types used by parsetree and typedtree. *)
+(** Auxiliary AST types used by parsetree and typedtree.
+
+  {b Warning:} this module is unstable and part of
+  {{!Compiler-libs}compiler-libs}.
+
+*)
 
 type constant =
     Const_int of int
diff --git a/parsing/attr_helper.mli b/parsing/attr_helper.mli
@@ -13,7 +13,12 @@
 (*                                                                        *)
 (**************************************************************************)
 
-(** Helpers for attributes *)
+(** Helpers for attributes
+
+  {b Warning:} this module is unstable and part of
+  {{!Compiler-libs}compiler-libs}.
+
+*)
 
 open Asttypes
 open Parsetree
diff --git a/parsing/builtin_attributes.mli b/parsing/builtin_attributes.mli
@@ -13,18 +13,22 @@
 (*                                                                        *)
 (**************************************************************************)
 
-(* Support for some of the builtin attributes:
-
-   ocaml.deprecated
-   ocaml.error
-   ocaml.ppwarning
-   ocaml.warning
-   ocaml.warnerror
-   ocaml.explicit_arity (for camlp4/camlp5)
-   ocaml.warn_on_literal_pattern
-   ocaml.deprecated_mutable
-   ocaml.immediate
-   ocaml.boxed / ocaml.unboxed
+(** Support for some of the builtin attributes
+
+    - ocaml.deprecated
+    - ocaml.error
+    - ocaml.ppwarning
+    - ocaml.warning
+    - ocaml.warnerror
+    - ocaml.explicit_arity (for camlp4/camlp5)
+    - ocaml.warn_on_literal_pattern
+    - ocaml.deprecated_mutable
+    - ocaml.immediate
+    - ocaml.boxed / ocaml.unboxed
+
+    {b Warning:} this module is unstable and part of
+  {{!Compiler-libs}compiler-libs}.
+
 *)
 
 
diff --git a/parsing/depend.mli b/parsing/depend.mli
@@ -13,7 +13,13 @@
 (*                                                                        *)
 (**************************************************************************)
 
-(** Module dependencies. *)
+(** Module dependencies.
+
+  {b Warning:} this module is unstable and part of
+  {{!Compiler-libs}compiler-libs}.
+
+*)
+
 module String = Misc.Stdlib.String
 
 type map_tree = Node of String.Set.t * bound_map
@@ -24,7 +30,7 @@ val weaken_map : String.Set.t -> map_tree -> map_tree
 
 val free_structure_names : String.Set.t ref
 
-(* dependencies found by preprocessing tools (plugins) *)
+(** dependencies found by preprocessing tools (plugins) *)
 val pp_deps : string list ref
 
 val open_module : bound_map -> Longident.t -> bound_map
diff --git a/parsing/docstrings.mli b/parsing/docstrings.mli
@@ -13,7 +13,12 @@
 (*                                                                        *)
 (**************************************************************************)
 
-(** Documentation comments *)
+(** Documentation comments
+
+  {b Warning:} this module is unstable and part of
+  {{!Compiler-libs}compiler-libs}.
+
+*)
 
 (** (Re)Initialise all docstring state *)
 val init : unit -> unit
diff --git a/parsing/lexer.mli b/parsing/lexer.mli
@@ -13,7 +13,12 @@
 (*                                                                        *)
 (**************************************************************************)
 
-(* The lexical analyzer *)
+(** The lexical analyzer
+
+  {b Warning:} this module is unstable and part of
+  {{!Compiler-libs}compiler-libs}.
+
+*)
 
 val init : unit -> unit
 val token: Lexing.lexbuf -> Parser.token
diff --git a/parsing/location.mli b/parsing/location.mli
@@ -13,7 +13,12 @@
 (*                                                                        *)
 (**************************************************************************)
 
-(** {1 Source code locations (ranges of positions), used in parsetree} *)
+(** {1 Source code locations (ranges of positions), used in parsetree}
+
+  {b Warning:} this module is unstable and part of
+  {{!Compiler-libs}compiler-libs}.
+
+*)
 
 open Format
 
diff --git a/parsing/longident.mli b/parsing/longident.mli
@@ -13,7 +13,12 @@
 (*                                                                        *)
 (**************************************************************************)
 
-(** Long identifiers, used in parsetree. *)
+(** Long identifiers, used in parsetree.
+
+  {b Warning:} this module is unstable and part of
+  {{!Compiler-libs}compiler-libs}.
+
+*)
 
 type t =
     Lident of string
diff --git a/parsing/parse.mli b/parsing/parse.mli
@@ -13,7 +13,12 @@
 (*                                                                        *)
 (**************************************************************************)
 
-(** Entry points in the parser *)
+(** Entry points in the parser
+
+  {b Warning:} this module is unstable and part of
+  {{!Compiler-libs}compiler-libs}.
+
+*)
 
 val implementation : Lexing.lexbuf -> Parsetree.structure
 val interface : Lexing.lexbuf -> Parsetree.signature
diff --git a/parsing/parsetree.mli b/parsing/parsetree.mli
@@ -13,7 +13,12 @@
 (*                                                                        *)
 (**************************************************************************)
 
-(** Abstract syntax tree produced by parsing *)
+(** Abstract syntax tree produced by parsing
+
+  {b Warning:} this module is unstable and part of
+  {{!Compiler-libs}compiler-libs}.
+
+*)
 
 open Asttypes
 
diff --git a/parsing/pprintast.mli b/parsing/pprintast.mli
@@ -13,6 +13,14 @@
 (*                                                                        *)
 (**************************************************************************)
 
+
+(** Pretty-printers for {!Parsetree}
+
+  {b Warning:} this module is unstable and part of
+  {{!Compiler-libs}compiler-libs}.
+
+*)
+
 type space_formatter = (unit, Format.formatter, unit) format
 
 val longident : Format.formatter -> Longident.t -> unit
diff --git a/parsing/printast.mli b/parsing/printast.mli
@@ -13,6 +13,13 @@
 (*                                                                        *)
 (**************************************************************************)
 
+(** Raw printer for {!Parsetree}
+
+  {b Warning:} this module is unstable and part of
+  {{!Compiler-libs}compiler-libs}.
+
+*)
+
 open Parsetree;;
 open Format;;
 
diff --git a/parsing/syntaxerr.mli b/parsing/syntaxerr.mli
@@ -13,7 +13,12 @@
 (*                                                                        *)
 (**************************************************************************)
 
-(** Auxiliary type for reporting syntax errors *)
+(** Auxiliary type for reporting syntax errors
+
+  {b Warning:} this module is unstable and part of
+  {{!Compiler-libs}compiler-libs}.
+
+*)
 
 open Format
 
diff --git a/typing/typemod.mli b/typing/typemod.mli
@@ -13,7 +13,12 @@
 (*                                                                        *)
 (**************************************************************************)
 
-(** Type-checking of the module language and typed ast plugin hooks *)
+(** Type-checking of the module language and typed ast plugin hooks
+
+  {b Warning:} this module is unstable and part of
+  {{!Compiler-libs}compiler-libs}.
+
+*)
 
 open Types
 open Format
diff --git a/utils/arg_helper.mli b/utils/arg_helper.mli
diff --git a/utils/build_path_prefix_map.mli b/utils/build_path_prefix_map.mli
diff --git a/utils/ccomp.mli b/utils/ccomp.mli
diff --git a/utils/config.mli b/utils/config.mli
diff --git a/utils/consistbl.mli b/utils/consistbl.mli
diff --git a/utils/identifiable.mli b/utils/identifiable.mli
diff --git a/utils/misc.mli b/utils/misc.mli
diff --git a/utils/numbers.mli b/utils/numbers.mli
diff --git a/utils/profile.mli b/utils/profile.mli
diff --git a/utils/strongly_connected_components.mli b/utils/strongly_connected_components.mli
diff --git a/utils/targetint.mli b/utils/targetint.mli
diff --git a/utils/terminfo.mli b/utils/terminfo.mli
diff --git a/utils/warnings.mli b/utils/warnings.mli
