Inherit top-comment from @inline includes

src/document/generator.ml

@@ -1132,7 +1132,7 @@ module Make (Syntax : SYNTAX) = struct
                 let items = Sectioning.comment_items c in
                 loop rest (List.rev_append items acc_items))
       in
-      (s.doc, loop s.items [])
+      (Lang.extract_signature_doc s, loop s.items [])
 
     and functor_parameter :
         Odoc_model.Lang.FunctorParameter.parameter -> DocumentedSrc.t =

src/model/lang.ml

@@ -470,3 +470,14 @@ let umty_of_mty : ModuleType.expr -> ModuleType.U.expr option = function
   | Functor _ -> None
   | TypeOf t -> Some (TypeOf t)
   | With { w_substitutions; w_expr; _ } -> Some (With (w_substitutions, w_expr))
+
+(** Query the top-comment of a signature. This is [s.doc] most of the time with
+    an exception for signature starting with an inline includes. *)
+let extract_signature_doc (s : Signature.t) =
+  match (s.doc, s.items) with
+  | [], Include { expansion; status = `Inline; _ } :: _ ->
+      (* A signature that starts with an [@inline] include inherits the
+         top-comment from the expansion. This comment is not rendered for
+         [include] items. *)
+      expansion.content.doc
+  | doc, _ -> doc

src/xref2/component.ml

@@ -2321,3 +2321,9 @@ let module_of_functor_argument (arg : FunctorParameter.parameter) =
     canonical = None;
     hidden = false;
   }
+
+(** This is equivalent to {!Lang.extract_signature_doc}. *)
+let extract_signature_doc (s : Signature.t) =
+  match (s.doc, s.items) with
+  | [], Include { expansion_; status = `Inline; _ } :: _ -> expansion_.doc
+  | doc, _ -> doc

src/xref2/component.mli

@@ -758,3 +758,5 @@ module Of_Lang : sig
 end
 
 val module_of_functor_argument : FunctorParameter.parameter -> Module.t
+
+val extract_signature_doc : Signature.t -> CComment.docs

src/xref2/link.ml

@@ -11,8 +11,22 @@ module Opt = struct
   let map f = function Some x -> Some (f x) | None -> None
 end
 
-let synopsis_from_comment parent docs =
-  Odoc_model.Comment.synopsis (Lang_of.docs parent docs)
+(** Equivalent to {!Comment.synopsis}. *)
+let synopsis_from_comment (docs : Component.CComment.docs) =
+  match docs with
+  | ({ value = #Comment.nestable_block_element; _ } as e) :: _ ->
+      (* Only the first element is considered. *)
+      Comment.synopsis [ e ]
+  | _ -> None
+
+let synopsis_of_module env (m : Component.Module.t) =
+  match synopsis_from_comment m.doc with
+  | Some _ as s -> s
+  | None -> (
+      (* If there is no doc, look at the expansion. *)
+      match Tools.signature_of_module env m with
+      | Ok sg -> synopsis_from_comment (Component.extract_signature_doc sg)
+      | Error _ -> None)
 
 exception Loop
 
@@ -158,15 +172,7 @@ and comment_nestable_block_element env parent
           (fun (r : Comment.module_reference) ->
             match Ref_tools.resolve_module_reference env r.module_reference with
             | Some (r, _, m) ->
-                let module_synopsis =
-                  match synopsis_from_comment parent m.doc with
-                  | Some _ as s -> s
-                  | None -> (
-                      (* If there is no doc, look at the expansion. *)
-                      match Tools.signature_of_module env m with
-                      | Ok sg -> synopsis_from_comment parent sg.doc
-                      | Error _ -> None)
-                in
+                let module_synopsis = synopsis_of_module env m in
                 { Comment.module_reference = `Resolved r; module_synopsis }
             | None -> r)
           refs

test/html/expect/test_package+ml/Toplevel_comments/Include_inline/index.html

@@ -21,6 +21,9 @@
    <h1>
     Module <code><span>Toplevel_comments.Include_inline</span></code>
    </h1>
+   <p>
+    Doc of <code>T</code>, part 2.
+   </p>
   </header>
   <div class="odoc-content">
    <div class="odoc-include">

test/html/expect/test_package+ml/Toplevel_comments/index.html

@@ -40,6 +40,11 @@ <h1>
     <div class="spec module" id="module-Include_inline">
      <a href="#module-Include_inline" class="anchor"></a><code><span><span class="keyword">module</span> </span><span><a href="Include_inline/index.html">Include_inline</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code>
     </div>
+    <div class="spec-doc">
+     <p>
+      Doc of <code>T</code>, part 2.
+     </p>
+    </div>
    </div>
    <div class="odoc-spec">
     <div class="spec module" id="module-Include_inline'">
@@ -55,6 +60,11 @@ <h1>
     <div class="spec module-type" id="module-type-Include_inline_T">
      <a href="#module-type-Include_inline_T" class="anchor"></a><code><span><span class="keyword">module</span> <span class="keyword">type</span> </span><span><a href="module-type-Include_inline_T/index.html">Include_inline_T</a></span><span> = <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code>
     </div>
+    <div class="spec-doc">
+     <p>
+      Doc of <code>T</code>, part 2.
+     </p>
+    </div>
    </div>
    <div class="odoc-spec">
     <div class="spec module-type" id="module-type-Include_inline_T'">

test/html/expect/test_package+ml/Toplevel_comments/module-type-Include_inline_T/index.html

@@ -21,6 +21,9 @@
    <h1>
     Module type <code><span>Toplevel_comments.Include_inline_T</span></code>
    </h1>
+   <p>
+    Doc of <code>T</code>, part 2.
+   </p>
   </header>
   <div class="odoc-content">
    <div class="odoc-include">

test/html/expect/test_package+re/Toplevel_comments/Include_inline/index.html

@@ -21,6 +21,9 @@
    <h1>
     Module <code><span>Toplevel_comments.Include_inline</span></code>
    </h1>
+   <p>
+    Doc of <code>T</code>, part 2.
+   </p>
   </header>
   <div class="odoc-content">
    <div class="odoc-include">

test/html/expect/test_package+re/Toplevel_comments/index.html

@@ -40,6 +40,11 @@ <h1>
     <div class="spec module" id="module-Include_inline">
      <a href="#module-Include_inline" class="anchor"></a><code><span><span class="keyword">module</span> </span><span><a href="Include_inline/index.html">Include_inline</a></span><span>: { ... }</span><span>;</span></code>
     </div>
+    <div class="spec-doc">
+     <p>
+      Doc of <code>T</code>, part 2.
+     </p>
+    </div>
    </div>
    <div class="odoc-spec">
     <div class="spec module" id="module-Include_inline'">
@@ -55,6 +60,11 @@ <h1>
     <div class="spec module-type" id="module-type-Include_inline_T">
      <a href="#module-type-Include_inline_T" class="anchor"></a><code><span><span class="keyword">module</span> <span class="keyword">type</span> </span><span><a href="module-type-Include_inline_T/index.html">Include_inline_T</a></span><span> = { ... }</span><span>;</span></code>
     </div>
+    <div class="spec-doc">
+     <p>
+      Doc of <code>T</code>, part 2.
+     </p>
+    </div>
    </div>
    <div class="odoc-spec">
     <div class="spec module-type" id="module-type-Include_inline_T'">

test/html/expect/test_package+re/Toplevel_comments/module-type-Include_inline_T/index.html

@@ -21,6 +21,9 @@
    <h1>
     Module type <code><span>Toplevel_comments.Include_inline_T</span></code>
    </h1>
+   <p>
+    Doc of <code>T</code>, part 2.
+   </p>
   </header>
   <div class="odoc-content">
    <div class="odoc-include">

test/xref2/module_list.t/run.t

@@ -32,7 +32,7 @@ Everything should resolve:
   {"`Resolved":{"`SubstAlias":[{"`Canonical":[{"`Module":[{"`Identifier":{"`Module":[{"`Root":[{"`RootPage":"test"},"Main"]},"Internal"]}},"C2"]},{"`Resolved":{"`Identifier":{"`Module":[{"`Root":[{"`RootPage":"test"},"Main"]},"C2"]}}}]},{"`Identifier":{"`Module":[{"`Root":[{"`RootPage":"test"},"Main"]},"C2"]}}]}}
   "None"
   {"`Resolved":{"`Identifier":{"`Module":[{"`Root":[{"`RootPage":"test"},"Main"]},"Inline_include"]}}}
-  "None"
+  {"Some":[{"`Word":"Doc"},"`Space",{"`Word":"for"},"`Space",{"`Code_span":"T"},{"`Word":"."}]}
   {"`Resolved":{"`Identifier":{"`Root":[{"`RootPage":"test"},"Starts_with_open"]}}}
   {"Some":[{"`Word":"Synopsis"},"`Space",{"`Word":"of"},"`Space",{"`Code_span":"Starts_with_open"},{"`Word":"."}]}