Remove unwanted or duplicate doc in expansions

CHANGES.md

@@ -39,6 +39,8 @@
 - Fixed title content not being picked up across pages when rendering references
   (#1116, @panglesd)
 - Fix wrong links to standalone comments in search results (#1118, @panglesd)
+- Remove duplicated or unwanted comments (@Julow, #1133)
+  This could happen with inline includes.
 
 
 # 2.4.0

src/xref2/tools.ml

@@ -1576,14 +1576,10 @@ and expansion_of_module_path :
       in
       expansion_of_module_cached env p' m >>= function
       | Signature sg ->
-          let sg' =
-            match m.doc with
-            | [] -> sg
-            | docs -> { sg with items = Comment (`Docs docs) :: sg.items }
+          let sg =
+            if strengthen then Strengthen.signature (`Resolved p') sg else sg
           in
-          if strengthen then
-            Ok (Signature (Strengthen.signature (`Resolved p') sg'))
-          else Ok (Signature sg')
+          Ok (Signature sg)
       | Functor _ as f -> Ok f)
   | Error _ when Cpath.is_module_forward path -> Error `UnresolvedForwardPath
   | Error e -> Error (`UnresolvedPath (`Module (path, e)))
@@ -1719,7 +1715,16 @@ and expansion_of_module :
     Env.t ->
     Component.Module.t ->
     (expansion, expansion_of_module_error) Result.result =
- fun env m -> expansion_of_module_decl env m.type_
+ fun env m ->
+  expansion_of_module_decl env m.type_ >>= function
+  | Signature sg ->
+      let sg =
+        (* Override the signature's documentation when the module also has
+           a comment attached. *)
+        match m.doc with [] -> sg | doc -> { sg with doc }
+      in
+      Ok (Signature sg)
+  | Functor _ as f -> Ok f
 
 and expansion_of_module_cached :
     Env.t ->

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}}}\\