Merge pull request #1037 from Octachron/ocamldoc_preamble_duplication

PR#7478: ocamldoc, avoid module preamble repetition

6 files changed, 58 insertions, 3 deletions

diff --git a/Changes b/Changes
index 94433df31c..2742ca6e49 100644
--- a/Changes
+++ b/Changes
@@ -204,6 +204,13 @@ Working version
 * MPR#7352,PR#7353: ocamldoc, better paragraphs in html output
   (Florian Angeletti, request by Daniel Bünzli)
 
+
+* MPR#7478, GPR#1037: ocamldoc, do not use as a module preamble documentation
+  comments that occur after the first module element. This change may break
+  existing documenation. In particular, module preambles must now come before
+  any `open` statement.
+  (Florian Angeletti, review by David Allsopp and report by Daniel Bünzli)
+
 - MPR#7521, GPR#1159: ocamldoc, end generated latex file with a new line
   (Florian Angeletti)
 
diff --git a/ocamldoc/odoc_ast.ml b/ocamldoc/odoc_ast.ml
index 511d9d1123..b1a027d403 100644
--- a/ocamldoc/odoc_ast.ml
+++ b/ocamldoc/odoc_ast.ml
@@ -1870,8 +1870,8 @@ module Analyser =
        prepare_file source_file input_file;
        (* We create the t_module for this file. *)
        let mod_name = String.capitalize_ascii (Filename.basename (Filename.chop_extension source_file)) in
-       let (len,info_opt) = My_ir.first_special !file_name !file in
-
+       let len, info_opt = Sig.preamble !file_name !file
+           (fun x -> x.Parsetree.pstr_loc) parsetree in
        (* we must complete the included modules *)
        let elements = analyse_structure Odoc_env.empty mod_name len (String.length !file) parsetree tree_structure in
        let included_modules_from_tt = tt_get_included_module_list tree_structure in
diff --git a/ocamldoc/odoc_sig.ml b/ocamldoc/odoc_sig.ml
index 18607f916c..7dc9b3a51f 100644
--- a/ocamldoc/odoc_sig.ml
+++ b/ocamldoc/odoc_sig.ml
@@ -185,6 +185,14 @@ module Analyser =
         !file_name
         (get_string_of_file pos_start pos_end)
 
+    let preamble filename file proj ast =
+      let info = My_ir.first_special filename file in
+      (* Only use as module preamble documentation comments that occur before
+           any module elements *)
+      match ast with
+      | a :: _ when  Loc.start (proj a) < fst info -> (0,None)
+      | _ -> info
+
     let merge_infos = Odoc_merge.merge_info_opt Odoc_types.all_merge_options
 
     (** Module for extracting documentation comments for record from different
@@ -1626,7 +1634,8 @@ module Analyser =
       let mod_name = String.capitalize_ascii
           (Filename.basename (try Filename.chop_extension source_file with _ -> source_file))
       in
-      let (len,info_opt) = My_ir.first_special !file_name !file in
+      let len, info_opt = preamble !file_name !file
+          (fun x -> x.Parsetree.psig_loc) ast in
       let elements =
         analyse_parsetree Odoc_env.empty signat mod_name len (String.length !file) ast
       in
diff --git a/ocamldoc/odoc_sig.mli b/ocamldoc/odoc_sig.mli
index ddd1160739..8864e9963d 100644
--- a/ocamldoc/odoc_sig.mli
+++ b/ocamldoc/odoc_sig.mli
@@ -127,6 +127,15 @@ module Analyser :
          [input_f] into [file].*)
       val prepare_file : string -> string -> unit
 
+      (** [preamble f input_f loc ast ] retrieves the position and contents of
+          the preamble for the file [f]: i.e, the first documentation comment
+          before any elements in [ast].
+          If there is no such preamble, [0,None] is returned.
+          The function [loc] is used to obtain the location of this
+          first element of [ast].*)
+      val preamble: string -> string -> ('a -> Location.t) -> 'a list
+        -> int * Odoc_types.info option
+
       (** The function used to get the comments in a class. *)
       val get_comments_in_class : int -> int ->
         (Odoc_types.info option * Odoc_class.class_element list)
diff --git a/testsuite/tests/tool-ocamldoc-html/No_preamble.mli b/testsuite/tests/tool-ocamldoc-html/No_preamble.mli
new file mode 100644
index 0000000000..2760e266fb
--- /dev/null
+++ b/testsuite/tests/tool-ocamldoc-html/No_preamble.mli
@@ -0,0 +1,5 @@
+
+open String
+
+(** This is a documentation comment for [x], not a module preamble. *)
+val x: unit
diff --git a/testsuite/tests/tool-ocamldoc-html/No_preamble.reference b/testsuite/tests/tool-ocamldoc-html/No_preamble.reference
new file mode 100644
index 0000000000..a244800bfe
--- /dev/null
+++ b/testsuite/tests/tool-ocamldoc-html/No_preamble.reference
@@ -0,0 +1,25 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<link rel="stylesheet" href="style.css" type="text/css">
+<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<link rel="Start" href="index.html">
+<link rel="Up" href="index.html">
+<link title="Index of values" rel=Appendix href="index_values.html">
+<link title="Index of modules" rel=Appendix href="index_modules.html">
+<link title="No_preamble" rel="Chapter" href="No_preamble.html"><title>No_preamble</title>
+</head>
+<body>
+<div class="navbar">&nbsp;<a class="up" href="index.html" title="Index">Up</a>
+&nbsp;</div>
+<h1>Module <a href="type_No_preamble.html">No_preamble</a></h1>
+
+<pre><span class="keyword">module</span> No_preamble: <code class="code"><span class="keyword">sig</span></code> <a href="No_preamble.html">..</a> <code class="code"><span class="keyword">end</span></code></pre><hr width="100%">
+
+<pre><span id="VALx"><span class="keyword">val</span> x</span> : <code class="type">unit</code></pre><div class="info ">
+<div class="info-desc">
+<p>This is a documentation comment for <code class="code">x</code>, not a module preamble.</p>
+</div>
+</div>
+</body></html>
\ No newline at end of file