Render documentation attached to includes

Julow · Julow · commit 1d08e6e46280 · 2021-03-19T18:46:28.000+01:00
Before, the attached documentation was removed and the synopsis from the
includee top-comment was used instead. Now, the attached documentation
is rendered entirely and the includee top-comment is not.

There is an exception, if there is no documentation attached to the
include, we render the synopsis extracted from the includee top-comment,
as before.
diff --git a/src/document/generator.ml b/src/document/generator.ml
@@ -1545,7 +1545,16 @@ module Make (Syntax : SYNTAX) = struct
       let content = { Include.content; status; summary } in
       let attr = [ "include" ] in
       let anchor = None in
-      let doc = Comment.synopsis ~decl_doc:[] ~expansion_doc:(Some sg_doc) in
+      let doc =
+        (* Documentation attached to includes behave differently than other
+           declarations, which show only the synopsis. We can't only show the
+           synopsis because no page is generated to render it and we'd loose
+           the full documentation.
+           As an exception, the synopsis from the expansion is used iff there
+           is no documentation. *)
+        if t.doc <> [] then Comment.to_ir t.doc
+        else Comment.synopsis ~decl_doc:[] ~expansion_doc:(Some sg_doc)
+      in
       Item.Include { attr; anchor; doc; content }
   end
 
diff --git a/test/html/expect/test_package+ml/Include2/Y_include_doc/index.html b/test/html/expect/test_package+ml/Include2/Y_include_doc/index.html
@@ -26,7 +26,7 @@ <h1>
    <div class="odoc-include">
     <div class="spec-doc">
      <p>
-      Top-comment of Y.
+      Doc attached to <code>include Y</code>. <code>Y</code>'s top-comment shouldn't appear here.
      </p>
     </div>
     <details open="open">
diff --git a/test/html/expect/test_package+ml/Toplevel_comments/Include_inline'/index.html b/test/html/expect/test_package+ml/Toplevel_comments/Include_inline'/index.html
@@ -32,7 +32,7 @@ <h1>
    <div class="odoc-include">
     <div class="spec-doc">
      <p>
-      Doc of <code>T</code>, part 2.
+      part 3
      </p>
     </div>
     <div class="odoc-spec">
diff --git a/test/html/expect/test_package+ml/Toplevel_comments/Include_inline/index.html b/test/html/expect/test_package+ml/Toplevel_comments/Include_inline/index.html
@@ -24,11 +24,6 @@ <h1>
   </header>
   <div class="odoc-content">
    <div class="odoc-include">
-    <div class="spec-doc">
-     <p>
-      Doc of <code>T</code>, part 2.
-     </p>
-    </div>
     <div class="odoc-spec">
      <div class="spec type" id="type-t">
       <a href="#type-t" class="anchor"></a><code><span><span class="keyword">type</span> t</span></code>
diff --git a/test/html/expect/test_package+ml/Toplevel_comments/module-type-Include_inline_T'/index.html b/test/html/expect/test_package+ml/Toplevel_comments/module-type-Include_inline_T'/index.html
@@ -32,7 +32,7 @@ <h1>
    <div class="odoc-include">
     <div class="spec-doc">
      <p>
-      Doc of <code>T</code>, part 2.
+      part 3
      </p>
     </div>
     <div class="odoc-spec">
diff --git a/test/html/expect/test_package+ml/Toplevel_comments/module-type-Include_inline_T/index.html b/test/html/expect/test_package+ml/Toplevel_comments/module-type-Include_inline_T/index.html
@@ -24,11 +24,6 @@ <h1>
   </header>
   <div class="odoc-content">
    <div class="odoc-include">
-    <div class="spec-doc">
-     <p>
-      Doc of <code>T</code>, part 2.
-     </p>
-    </div>
     <div class="odoc-spec">
      <div class="spec type" id="type-t">
       <a href="#type-t" class="anchor"></a><code><span><span class="keyword">type</span> t</span></code>
diff --git a/test/html/expect/test_package+re/Include2/Y_include_doc/index.html b/test/html/expect/test_package+re/Include2/Y_include_doc/index.html
@@ -26,7 +26,7 @@ <h1>
    <div class="odoc-include">
     <div class="spec-doc">
      <p>
-      Top-comment of Y.
+      Doc attached to <code>include Y</code>. <code>Y</code>'s top-comment shouldn't appear here.
      </p>
     </div>
     <details open="open">
diff --git a/test/html/expect/test_package+re/Toplevel_comments/Include_inline'/index.html b/test/html/expect/test_package+re/Toplevel_comments/Include_inline'/index.html
@@ -32,7 +32,7 @@ <h1>
    <div class="odoc-include">
     <div class="spec-doc">
      <p>
-      Doc of <code>T</code>, part 2.
+      part 3
      </p>
     </div>
     <div class="odoc-spec">
diff --git a/test/html/expect/test_package+re/Toplevel_comments/Include_inline/index.html b/test/html/expect/test_package+re/Toplevel_comments/Include_inline/index.html
@@ -24,11 +24,6 @@ <h1>
   </header>
   <div class="odoc-content">
    <div class="odoc-include">
-    <div class="spec-doc">
-     <p>
-      Doc of <code>T</code>, part 2.
-     </p>
-    </div>
     <div class="odoc-spec">
      <div class="spec type" id="type-t">
       <a href="#type-t" class="anchor"></a><code><span><span class="keyword">type</span> t</span><span>;</span></code>
diff --git a/test/html/expect/test_package+re/Toplevel_comments/module-type-Include_inline_T'/index.html b/test/html/expect/test_package+re/Toplevel_comments/module-type-Include_inline_T'/index.html
@@ -32,7 +32,7 @@ <h1>
    <div class="odoc-include">
     <div class="spec-doc">
      <p>
-      Doc of <code>T</code>, part 2.
+      part 3
      </p>
     </div>
     <div class="odoc-spec">
diff --git a/test/html/expect/test_package+re/Toplevel_comments/module-type-Include_inline_T/index.html b/test/html/expect/test_package+re/Toplevel_comments/module-type-Include_inline_T/index.html
@@ -24,11 +24,6 @@ <h1>
   </header>
   <div class="odoc-content">
    <div class="odoc-include">
-    <div class="spec-doc">
-     <p>
-      Doc of <code>T</code>, part 2.
-     </p>
-    </div>
     <div class="odoc-spec">
      <div class="spec type" id="type-t">
       <a href="#type-t" class="anchor"></a><code><span><span class="keyword">type</span> t</span><span>;</span></code>
diff --git a/test/latex/expect/test_package+ml/Include2.tex b/test/latex/expect/test_package+ml/Include2.tex
@@ -14,7 +14,7 @@ \section{Module \ocamlinlinecode{Include2}}\label{container-page-test+u+package+
 \end{ocamlindent}%
 \ocamlcodefragment{\ocamltag{keyword}{end}}\begin{ocamlindent}The \ocamlinlinecode{include Y} below should have the synopsis from \ocamlinlinecode{Y}'s top-comment attached to it.\end{ocamlindent}%
 \medbreak
-\label{container-page-test+u+package+++ml-module-Include2-module-Y+u+include+u+doc}\ocamlcodefragment{\ocamltag{keyword}{module} \hyperref[container-page-test+u+package+++ml-module-Include2-module-Y+u+include+u+doc]{\ocamlinlinecode{Y\_\allowbreak{}include\_\allowbreak{}doc}}}\ocamlcodefragment{ : \ocamltag{keyword}{sig}}\begin{ocamlindent}Top-comment of Y.\ocamltag{keyword}{include} \ocamltag{keyword}{module} \ocamltag{keyword}{type} \ocamltag{keyword}{of} \ocamltag{keyword}{struct} \ocamltag{keyword}{include} \hyperref[container-page-test+u+package+++ml-module-Include2-module-Y]{\ocamlinlinecode{Y}} \ocamltag{keyword}{end}\label{container-page-test+u+package+++ml-module-Include2-module-Y+u+include+u+doc-type-t}\ocamlcodefragment{\ocamltag{keyword}{type} t = \hyperref[container-page-test+u+package+++ml-module-Include2-module-Y-type-t]{\ocamlinlinecode{Y.\allowbreak{}t}}}\\
+\label{container-page-test+u+package+++ml-module-Include2-module-Y+u+include+u+doc}\ocamlcodefragment{\ocamltag{keyword}{module} \hyperref[container-page-test+u+package+++ml-module-Include2-module-Y+u+include+u+doc]{\ocamlinlinecode{Y\_\allowbreak{}include\_\allowbreak{}doc}}}\ocamlcodefragment{ : \ocamltag{keyword}{sig}}\begin{ocamlindent}Doc attached to \ocamlinlinecode{include Y}. \ocamlinlinecode{Y}'s top-comment shouldn't appear here.\ocamltag{keyword}{include} \ocamltag{keyword}{module} \ocamltag{keyword}{type} \ocamltag{keyword}{of} \ocamltag{keyword}{struct} \ocamltag{keyword}{include} \hyperref[container-page-test+u+package+++ml-module-Include2-module-Y]{\ocamlinlinecode{Y}} \ocamltag{keyword}{end}\label{container-page-test+u+package+++ml-module-Include2-module-Y+u+include+u+doc-type-t}\ocamlcodefragment{\ocamltag{keyword}{type} t = \hyperref[container-page-test+u+package+++ml-module-Include2-module-Y-type-t]{\ocamlinlinecode{Y.\allowbreak{}t}}}\\
 \end{ocamlindent}%
 \ocamlcodefragment{\ocamltag{keyword}{end}}\\
 
