Remove unwanted or duplicate doc in expansions

A module's `doc` field was propagated through expansions by synthetizing
a comment at the top of the expanded signature. It's now propagated via
the `doc` field of the signature.

In the case where the module has a comment and the signature has a
top-comment, the module's comment is not propagated.

This fixes doc appearing multiple time when the signature is expanded
mutliple time (eg. due to an include-module-type-of) and doc appearing
when they shouldn't (eg. in a non-inline include).
This also moves the preambles into the right section in the generated
HTML.

src/xref2/tools.ml

@@ -1579,7 +1579,7 @@ and expansion_of_module_path :
           let sg' =
             match m.doc with
             | [] -> sg
-            | docs -> { sg with items = Comment (`Docs docs) :: sg.items }
+            | doc -> { sg with doc }
           in
           if strengthen then
             Ok (Signature (Strengthen.signature (`Resolved p') sg'))

test/generators/html/Include2.html

@@ -40,7 +40,6 @@ <h1>Module <code><span>Include2</span></code></h1>
        </span>
       </code>
      </summary>
-     <p>Comment about X that should not appear when including X below.</p>
      <div class="odoc-spec">
       <div class="spec type anchored" id="type-t">
        <a href="#type-t" class="anchor"></a>

test/generators/html/Ocamlary-FunctorTypeOf-argument-1-Collection.html

@@ -15,9 +15,9 @@
   </nav>
   <header class="odoc-preamble">
    <h1>Parameter <code><span>FunctorTypeOf.Collection</span></code></h1>
+   <p>This comment is for <code>CollectionModule</code>.</p>
   </header>
   <div class="odoc-content">
-   <p>This comment is for <code>CollectionModule</code>.</p>
    <div class="odoc-spec">
     <div class="spec type anchored" id="type-collection">
      <a href="#type-collection" class="anchor"></a>

test/generators/html/Ocamlary-Recollection-argument-1-C.html

@@ -14,9 +14,9 @@
   </nav>
   <header class="odoc-preamble">
    <h1>Parameter <code><span>Recollection.C</span></code></h1>
+   <p>This comment is for <code>CollectionModule</code>.</p>
   </header>
   <div class="odoc-content">
-   <p>This comment is for <code>CollectionModule</code>.</p>
    <div class="odoc-spec">
     <div class="spec type anchored" id="type-collection">
      <a href="#type-collection" class="anchor"></a>

test/generators/html/Ocamlary-Recollection.html

@@ -13,6 +13,7 @@
   </nav>
   <header class="odoc-preamble">
    <h1>Module <code><span>Ocamlary.Recollection</span></code></h1>
+   <p>This comment is for <code>CollectionModule</code>.</p>
   </header>
   <nav class="odoc-toc">
    <ul><li><a href="#parameters">Parameters</a></li>
@@ -33,7 +34,6 @@ <h2 id="parameters"><a href="#parameters" class="anchor"></a>Parameters
     </div>
    </div>
    <h2 id="signature"><a href="#signature" class="anchor"></a>Signature</h2>
-   <p>This comment is for <code>CollectionModule</code>.</p>
    <div class="odoc-spec">
     <div class="spec type anchored" id="type-collection">
      <a href="#type-collection" class="anchor"></a>

test/generators/html/Ocamlary-module-type-A-Q.html

@@ -13,9 +13,9 @@
    <a href="Ocamlary-module-type-A.html">A</a> &#x00BB; Q
   </nav>
   <header class="odoc-preamble"><h1>Module <code><span>A.Q</span></code></h1>
+   <p>This comment is for <code>CollectionModule</code>.</p>
   </header>
   <div class="odoc-content">
-   <p>This comment is for <code>CollectionModule</code>.</p>
    <div class="odoc-spec">
     <div class="spec type anchored" id="type-collection">
      <a href="#type-collection" class="anchor"></a>

test/generators/html/Ocamlary-module-type-A.html

@@ -32,6 +32,9 @@ <h1>Module type <code><span>Ocamlary.A</span></code></h1>
       </span>
      </code>
     </div>
+    <div class="spec-doc">
+     <p>This comment is for <code>CollectionModule</code>.</p>
+    </div>
    </div>
   </div>
  </body>

test/generators/html/Ocamlary-module-type-B-Q.html

@@ -13,9 +13,9 @@
    <a href="Ocamlary-module-type-B.html">B</a> &#x00BB; Q
   </nav>
   <header class="odoc-preamble"><h1>Module <code><span>B.Q</span></code></h1>
+   <p>This comment is for <code>CollectionModule</code>.</p>
   </header>
   <div class="odoc-content">
-   <p>This comment is for <code>CollectionModule</code>.</p>
    <div class="odoc-spec">
     <div class="spec type anchored" id="type-collection">
      <a href="#type-collection" class="anchor"></a>

test/generators/html/Ocamlary-module-type-B.html

@@ -32,6 +32,9 @@ <h1>Module type <code><span>Ocamlary.B</span></code></h1>
       </span>
      </code>
     </div>
+    <div class="spec-doc">
+     <p>This comment is for <code>CollectionModule</code>.</p>
+    </div>
    </div>
   </div>
  </body>

test/generators/html/Ocamlary-module-type-C-Q.html

@@ -13,9 +13,9 @@
    <a href="Ocamlary-module-type-C.html">C</a> &#x00BB; Q
   </nav>
   <header class="odoc-preamble"><h1>Module <code><span>C.Q</span></code></h1>
+   <p>This comment is for <code>CollectionModule</code>.</p>
   </header>
   <div class="odoc-content">
-   <p>This comment is for <code>CollectionModule</code>.</p>
    <div class="odoc-spec">
     <div class="spec type anchored" id="type-collection">
      <a href="#type-collection" class="anchor"></a>

test/generators/html/Ocamlary-module-type-C.html

@@ -50,6 +50,9 @@ <h1>Module type <code><span>Ocamlary.C</span></code></h1>
         </span>
        </code>
       </div>
+      <div class="spec-doc">
+       <p>This comment is for <code>CollectionModule</code>.</p>
+      </div>
      </div>
     </details>
    </div>

test/generators/html/Ocamlary-module-type-COLLECTION.html

@@ -14,9 +14,9 @@
   <header class="odoc-preamble">
    <h1>Module type <code><span>Ocamlary.COLLECTION</span></code></h1>
    <p>module type of</p>
+   <p>This comment is for <code>CollectionModule</code>.</p>
   </header>
   <div class="odoc-content">
-   <p>This comment is for <code>CollectionModule</code>.</p>
    <div class="odoc-spec">
     <div class="spec type anchored" id="type-collection">
      <a href="#type-collection" class="anchor"></a>

test/generators/html/Ocamlary-module-type-MMM-C.html

@@ -14,9 +14,9 @@
   </nav>
   <header class="odoc-preamble">
    <h1>Module <code><span>MMM.C</span></code></h1>
+   <p>This comment is for <code>CollectionModule</code>.</p>
   </header>
   <div class="odoc-content">
-   <p>This comment is for <code>CollectionModule</code>.</p>
    <div class="odoc-spec">
     <div class="spec type anchored" id="type-collection">
      <a href="#type-collection" class="anchor"></a>

test/generators/html/Ocamlary-module-type-MMM.html

@@ -26,6 +26,9 @@ <h1>Module type <code><span>Ocamlary.MMM</span></code></h1>
       </span>
      </code>
     </div>
+    <div class="spec-doc">
+     <p>This comment is for <code>CollectionModule</code>.</p>
+    </div>
    </div>
   </div>
  </body>

test/generators/html/Ocamlary.html

@@ -718,6 +718,9 @@ <h4 id="advanced-module-stuff">
       </span>
      </code>
     </div>
+    <div class="spec-doc">
+     <p>This comment is for <code>CollectionModule</code>.</p>
+    </div>
    </div>
    <div class="odoc-spec">
     <div class="spec module-type anchored" id="module-type-MMM">

test/generators/latex/Include2.tex

@@ -3,9 +3,7 @@ \section{Module \ocamlinlinecode{Include2}}\label{module-Include2}%
 \end{ocamlindent}%
 \ocamlcodefragment{\ocamltag{keyword}{end}}\begin{ocamlindent}Comment about X that should not appear when including X below.\end{ocamlindent}%
 \medbreak
-\ocamltag{keyword}{include} \ocamltag{keyword}{module} \ocamltag{keyword}{type} \ocamltag{keyword}{of} \ocamltag{keyword}{struct} \ocamltag{keyword}{include} \hyperref[module-Include2-module-X]{\ocamlinlinecode{X}} \ocamltag{keyword}{end}Comment about X that should not appear when including X below.
-
-\label{module-Include2-type-t}\ocamlcodefragment{\ocamltag{keyword}{type} t = int}\\
+\ocamltag{keyword}{include} \ocamltag{keyword}{module} \ocamltag{keyword}{type} \ocamltag{keyword}{of} \ocamltag{keyword}{struct} \ocamltag{keyword}{include} \hyperref[module-Include2-module-X]{\ocamlinlinecode{X}} \ocamltag{keyword}{end}\label{module-Include2-type-t}\ocamlcodefragment{\ocamltag{keyword}{type} t = int}\\
 \label{module-Include2-module-Y}\ocamlcodefragment{\ocamltag{keyword}{module} \hyperref[module-Include2-module-Y]{\ocamlinlinecode{Y}}}\ocamlcodefragment{ : \ocamltag{keyword}{sig}}\begin{ocamlindent}\label{module-Include2-module-Y-type-t}\ocamlcodefragment{\ocamltag{keyword}{type} t}\\
 \end{ocamlindent}%
 \ocamlcodefragment{\ocamltag{keyword}{end}}\begin{ocamlindent}Top-comment of Y.\end{ocamlindent}%

test/generators/latex/Ocamlary.FunctorTypeOf.tex

@@ -2,9 +2,7 @@ \section{Module \ocamlinlinecode{Ocamlary.\allowbreak{}FunctorTypeOf}}\label{mod
 This comment is for \ocamlinlinecode{FunctorTypeOf}.
 
 \subsection{Parameters\label{parameters}}%
-\label{module-Ocamlary-module-FunctorTypeOf-argument-1-Collection}\ocamlcodefragment{\ocamltag{keyword}{module} \hyperref[module-Ocamlary-module-FunctorTypeOf-argument-1-Collection]{\ocamlinlinecode{Collection}}}\ocamlcodefragment{ : \ocamltag{keyword}{sig}}\begin{ocamlindent}This comment is for \ocamlinlinecode{CollectionModule}.
-
-\label{module-Ocamlary-module-FunctorTypeOf-argument-1-Collection-type-collection}\ocamlcodefragment{\ocamltag{keyword}{type} collection}\begin{ocamlindent}This comment is for \ocamlinlinecode{collection}.\end{ocamlindent}%
+\label{module-Ocamlary-module-FunctorTypeOf-argument-1-Collection}\ocamlcodefragment{\ocamltag{keyword}{module} \hyperref[module-Ocamlary-module-FunctorTypeOf-argument-1-Collection]{\ocamlinlinecode{Collection}}}\ocamlcodefragment{ : \ocamltag{keyword}{sig}}\begin{ocamlindent}\label{module-Ocamlary-module-FunctorTypeOf-argument-1-Collection-type-collection}\ocamlcodefragment{\ocamltag{keyword}{type} collection}\begin{ocamlindent}This comment is for \ocamlinlinecode{collection}.\end{ocamlindent}%
 \medbreak
 \label{module-Ocamlary-module-FunctorTypeOf-argument-1-Collection-type-element}\ocamlcodefragment{\ocamltag{keyword}{type} element}\\
 \label{module-Ocamlary-module-FunctorTypeOf-argument-1-Collection-module-InnerModuleA}\ocamlcodefragment{\ocamltag{keyword}{module} \hyperref[module-Ocamlary-module-FunctorTypeOf-argument-1-Collection-module-InnerModuleA]{\ocamlinlinecode{InnerModuleA}}}\ocamlcodefragment{ : \ocamltag{keyword}{sig}}\begin{ocamlindent}\label{module-Ocamlary-module-FunctorTypeOf-argument-1-Collection-module-InnerModuleA-type-t}\ocamlcodefragment{\ocamltag{keyword}{type} t = \hyperref[module-Ocamlary-module-FunctorTypeOf-argument-1-Collection-type-collection]{\ocamlinlinecode{collection}}}\begin{ocamlindent}This comment is for \ocamlinlinecode{t}.\end{ocamlindent}%

test/generators/latex/Ocamlary.Recollection.tex

@@ -1,8 +1,8 @@
 \section{Module \ocamlinlinecode{Ocamlary.\allowbreak{}Recollection}}\label{module-Ocamlary-module-Recollection}%
-\subsection{Parameters\label{parameters}}%
-\label{module-Ocamlary-module-Recollection-argument-1-C}\ocamlcodefragment{\ocamltag{keyword}{module} \hyperref[module-Ocamlary-module-Recollection-argument-1-C]{\ocamlinlinecode{C}}}\ocamlcodefragment{ : \ocamltag{keyword}{sig}}\begin{ocamlindent}This comment is for \ocamlinlinecode{CollectionModule}.
+This comment is for \ocamlinlinecode{CollectionModule}.
 
-\label{module-Ocamlary-module-Recollection-argument-1-C-type-collection}\ocamlcodefragment{\ocamltag{keyword}{type} collection}\begin{ocamlindent}This comment is for \ocamlinlinecode{collection}.\end{ocamlindent}%
+\subsection{Parameters\label{parameters}}%
+\label{module-Ocamlary-module-Recollection-argument-1-C}\ocamlcodefragment{\ocamltag{keyword}{module} \hyperref[module-Ocamlary-module-Recollection-argument-1-C]{\ocamlinlinecode{C}}}\ocamlcodefragment{ : \ocamltag{keyword}{sig}}\begin{ocamlindent}\label{module-Ocamlary-module-Recollection-argument-1-C-type-collection}\ocamlcodefragment{\ocamltag{keyword}{type} collection}\begin{ocamlindent}This comment is for \ocamlinlinecode{collection}.\end{ocamlindent}%
 \medbreak
 \label{module-Ocamlary-module-Recollection-argument-1-C-type-element}\ocamlcodefragment{\ocamltag{keyword}{type} element}\\
 \label{module-Ocamlary-module-Recollection-argument-1-C-module-InnerModuleA}\ocamlcodefragment{\ocamltag{keyword}{module} \hyperref[module-Ocamlary-module-Recollection-argument-1-C-module-InnerModuleA]{\ocamlinlinecode{InnerModuleA}}}\ocamlcodefragment{ : \ocamltag{keyword}{sig}}\begin{ocamlindent}\label{module-Ocamlary-module-Recollection-argument-1-C-module-InnerModuleA-type-t}\ocamlcodefragment{\ocamltag{keyword}{type} t = \hyperref[module-Ocamlary-module-Recollection-argument-1-C-type-collection]{\ocamlinlinecode{collection}}}\begin{ocamlindent}This comment is for \ocamlinlinecode{t}.\end{ocamlindent}%
@@ -25,8 +25,6 @@ \subsection{Parameters\label{parameters}}%
 \end{ocamlindent}%
 \ocamlcodefragment{\ocamltag{keyword}{end}}\\
 \subsection{Signature\label{signature}}%
-This comment is for \ocamlinlinecode{CollectionModule}.
-
 \label{module-Ocamlary-module-Recollection-type-collection}\ocamlcodefragment{\ocamltag{keyword}{type} collection = \hyperref[module-Ocamlary-module-Recollection-argument-1-C-type-element]{\ocamlinlinecode{C.\allowbreak{}element}} list}\begin{ocamlindent}This comment is for \ocamlinlinecode{collection}.\end{ocamlindent}%
 \medbreak
 \label{module-Ocamlary-module-Recollection-type-element}\ocamlcodefragment{\ocamltag{keyword}{type} element = \hyperref[module-Ocamlary-module-Recollection-argument-1-C-type-collection]{\ocamlinlinecode{C.\allowbreak{}collection}}}\\