Take expansion's doc when computing a declaration's synopsis

src/document/comment.ml

@@ -227,9 +227,7 @@ let module_references ms =
 let rec nestable_block_element : Comment.nestable_block_element -> Block.one =
  fun content ->
   match content with
-  | `Paragraph [ { value = `Raw_markup (target, s); _ } ] ->
-      block @@ Block.Raw_markup (target, s)
-  | `Paragraph content -> block @@ Block.Paragraph (inline_element_list content)
+  | `Paragraph p -> paragraph p
   | `Code_block code -> block @@ Source (source_of_code code)
   | `Verbatim s -> block @@ Verbatim s
   | `Modules ms -> module_references ms
@@ -247,6 +245,11 @@ let rec nestable_block_element : Comment.nestable_block_element -> Block.one =
       let items = List.map f items in
       block @@ Block.List (kind, items)
 
+and paragraph : Comment.paragraph -> Block.one = function
+  | [ { value = `Raw_markup (target, s); _ } ] ->
+      block @@ Block.Raw_markup (target, s)
+  | p -> block @@ Block.Paragraph (inline_element_list p)
+
 and nestable_block_element_list elements =
   elements
   |> List.map Odoc_model.Location_.value
@@ -329,10 +332,11 @@ let item_element : Comment.block_element -> Item.t list = function
       [ Item.Text (attached_block_element e) ]
   | `Heading _ as h -> [ heading h ]
 
-let first_to_ir = function
-  | { Odoc_model.Location_.value = `Paragraph _ as first_paragraph; _ } :: _ ->
-      block_element first_paragraph
-  | _ -> []
+(** The documentation of the expansion is used if there is no comment attached
+    to the declaration. *)
+let synopsis ~decl_doc ~expansion_doc =
+  let ([], Some docs | docs, _) = (decl_doc, expansion_doc) in
+  match Comment.synopsis docs with Some p -> [ paragraph p ] | None -> []
 
 let standalone docs =
   Utils.flatmap ~f:item_element

src/document/generator.ml

@@ -994,16 +994,18 @@ module Make (Syntax : SYNTAX) = struct
         if t.virtual_ then O.keyword "virtual" ++ O.txt " " else O.noop
       in
 
-      let cname, expansion =
+      let cname, expansion, expansion_doc =
         match t.expansion with
-        | None -> (O.documentedSrc @@ O.txt name, None)
+        | None -> (O.documentedSrc @@ O.txt name, None, None)
         | Some csig ->
             let expansion_doc, items = class_signature csig in
             let url = Url.Path.from_identifier t.id in
             let page =
               make_expansion_page name `Class url [ t.doc; expansion_doc ] items
             in
-            (O.documentedSrc @@ path url [ inline @@ Text name ], Some page)
+            ( O.documentedSrc @@ path url [ inline @@ Text name ],
+              Some page,
+              Some expansion_doc )
       in
       let summary =
         O.txt Syntax.Type.annotation_separator ++ class_decl t.type_
@@ -1020,7 +1022,7 @@ module Make (Syntax : SYNTAX) = struct
       in
       let attr = [ "class" ] in
       let anchor = path_to_id t.id in
-      let doc = Comment.first_to_ir t.doc in
+      let doc = Comment.synopsis ~decl_doc:t.doc ~expansion_doc in
       Item.Declaration { attr; anchor; doc; content }
 
     let class_type (t : Odoc_model.Lang.ClassType.t) =
@@ -1029,16 +1031,18 @@ module Make (Syntax : SYNTAX) = struct
       let virtual_ =
         if t.virtual_ then O.keyword "virtual" ++ O.txt " " else O.noop
       in
-      let cname, expansion =
+      let cname, expansion, expansion_doc =
         match t.expansion with
-        | None -> (O.documentedSrc @@ O.txt name, None)
+        | None -> (O.documentedSrc @@ O.txt name, None, None)
         | Some csig ->
             let url = Url.Path.from_identifier t.id in
             let expansion_doc, items = class_signature csig in
             let page =
               make_expansion_page name `Cty url [ t.doc; expansion_doc ] items
             in
-            (O.documentedSrc @@ path url [ inline @@ Text name ], Some page)
+            ( O.documentedSrc @@ path url [ inline @@ Text name ],
+              Some page,
+              Some expansion_doc )
       in
       let summary = O.txt " = " ++ class_type_expr t.expr in
       let expr = attach_expansion (" = ", "object", "end") expansion summary in
@@ -1050,7 +1054,7 @@ module Make (Syntax : SYNTAX) = struct
       in
       let attr = [ "class-type" ] in
       let anchor = path_to_id t.id in
-      let doc = Comment.first_to_ir t.doc in
+      let doc = Comment.synopsis ~decl_doc:t.doc ~expansion_doc in
       Item.Declaration { attr; anchor; doc; content }
   end
 
@@ -1265,9 +1269,9 @@ module Make (Syntax : SYNTAX) = struct
         | Alias (_, None) -> None
         | ModuleType e -> expansion_of_module_type_expr e
       in
-      let modname, status, expansion =
+      let modname, status, expansion, expansion_doc =
         match expansion with
-        | None -> (O.documentedSrc (O.txt modname), `Default, None)
+        | None -> (O.documentedSrc (O.txt modname), `Default, None, None)
         | Some (expansion_doc, items) ->
             let status =
               match t.type_ with
@@ -1280,7 +1284,7 @@ module Make (Syntax : SYNTAX) = struct
               make_expansion_page modname `Mod url [ t.doc; expansion_doc ]
                 items
             in
-            (O.documentedSrc link, status, Some page)
+            (O.documentedSrc link, status, Some page, Some expansion_doc)
       in
       let summary = mdexpr_in_decl t.id t.type_ in
       let modexpr =
@@ -1296,7 +1300,7 @@ module Make (Syntax : SYNTAX) = struct
       in
       let attr = [ "module" ] in
       let anchor = path_to_id t.id in
-      let doc = Comment.first_to_ir t.doc in
+      let doc = Comment.synopsis ~decl_doc:t.doc ~expansion_doc in
       Item.Declaration { attr; anchor; doc; content }
 
     and simple_expansion_in_decl (base : Paths.Identifier.Module.t) se =
@@ -1330,17 +1334,17 @@ module Make (Syntax : SYNTAX) = struct
         | None -> None
         | Some e -> expansion_of_module_type_expr e
       in
-      let modname, expansion =
+      let modname, expansion, expansion_doc =
         match expansion with
-        | None -> (O.documentedSrc @@ O.txt modname, None)
+        | None -> (O.documentedSrc @@ O.txt modname, None, None)
         | Some (expansion_doc, items) ->
             let url = Url.Path.from_identifier t.id in
             let link = path url [ inline @@ Text modname ] in
             let page =
               make_expansion_page modname `Mty url [ t.doc; expansion_doc ]
                 items
             in
-            (O.documentedSrc link, Some page)
+            (O.documentedSrc link, Some page, Some expansion_doc)
       in
       let summary =
         match t.expr with
@@ -1357,7 +1361,7 @@ module Make (Syntax : SYNTAX) = struct
       in
       let attr = [ "module-type" ] in
       let anchor = path_to_id t.id in
-      let doc = Comment.first_to_ir t.doc in
+      let doc = Comment.synopsis ~decl_doc:t.doc ~expansion_doc in
       Item.Declaration { attr; anchor; doc; content }
 
     and umty_hidden : Odoc_model.Lang.ModuleType.U.expr -> bool = function
@@ -1541,7 +1545,7 @@ module Make (Syntax : SYNTAX) = struct
       let content = { Include.content; status; summary } in
       let attr = [ "include" ] in
       let anchor = None in
-      let doc = Comment.first_to_ir sg_doc in
+      let doc = Comment.synopsis ~decl_doc:[] ~expansion_doc:(Some sg_doc) in
       Item.Include { attr; anchor; doc; content }
   end
 

src/model/comment.ml

@@ -85,3 +85,9 @@ type block_element =
 type docs = block_element with_location list
 
 type docs_or_stop = [ `Docs of docs | `Stop ]
+
+(** The synopsis is the first element of a comment if it is a paragraph.
+    Otherwise, there is no synopsis. *)
+let synopsis = function
+  | { Location_.value = `Paragraph p; _ } :: _ -> Some p
+  | _ -> None

src/odoc/interface.mld

@@ -26,8 +26,9 @@ The following describes the changes between what odoc understands and what is in
 - {{:https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#ss:ocamldoc-formatting}Alignment elements} are not handled ([{C text}], [{L text}] and [{R text}]) ({{:https://github.com/ocaml/odoc/issues/541}github issue})
 - Odoc does not recognise {{:https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#sss:ocamldoc-html-tags}html tags embedded in comments} ({{:https://github.com/ocaml/odoc/issues/576}github issue})
 - [{!indexlist}] is not supported ({{:https://github.com/ocaml/odoc/issues/577}github issue})
-- When rendering [{!modules:...}] lists, the first paragraph is used instead of
-  the {{:https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#sss:ocamldoc-preamble}first sentence}.
+- The first paragraph is used for synopses instead of the {{:https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#sss:ocamldoc-preamble}first sentence}.
+  Synopses are used when rendering declarations (of modules, classes, etc..) and [{!modules:...}] lists.
+  An other difference is that documentation starting with a heading or something that is not a paragraph won't have a synopsis ({{:https://github.com/ocaml/odoc/pull/643}github issue}).
 
 {4 Improvements}
 - Odoc has a better mechanism for disambiguating references in comments. See 'reference syntax' later in this document.