Do not drop comments attached to open

CHANGES.md

@@ -5,6 +5,10 @@ Bugs fixed
 - Fix a missing Result constructor during compile. This will cause some
   functor arguments to have different filenames (@jonludlam, #795)
 
+Additions
+- Handle comments attached to open statement as floating comment, instead
+  of dropping them (@panglesd, #797)
+
 2.0.2
 -----
 

src/document/generator.ml

@@ -1154,7 +1154,9 @@ module Make (Syntax : SYNTAX) = struct
             | TypExt e -> continue @@ extension e
             | Exception e -> continue @@ exn e
             | Value v -> continue @@ value v
-            | Open _ -> loop rest acc_items
+            | Open o ->
+                let items = Sectioning.comment_items o.doc in
+                loop rest (List.rev_append items acc_items)
             | Comment `Stop ->
                 let rest =
                   Utils.skip_until rest ~p:(function

src/loader/cmt.ml

@@ -568,8 +568,10 @@ and read_include env parent incl =
 
 #if OCAML_VERSION >= (4,8,0)
 and read_open env parent o =
+  let container = (parent : Identifier.Signature.t :> Identifier.LabelParent.t) in
+  let doc = Doc_attr.attached_no_tag container o.open_attributes in
   let expansion, _ = Cmi.read_signature_noenv env parent (Odoc_model.Compat.signature o.open_bound_items) in
-  Open.{expansion}
+  Open.{expansion; doc}
 #endif
 
 and read_structure :

src/loader/cmti.ml

@@ -775,8 +775,10 @@ and read_include env parent incl =
 
 #if OCAML_VERSION >= (4,8,0)
 and read_open env parent o =
+  let container = (parent : Identifier.Signature.t :> Identifier.LabelParent.t) in
+  let doc = Doc_attr.attached_no_tag container o.open_attributes in
   let expansion, _ = Cmi.read_signature_noenv env parent (Odoc_model.Compat.signature o.open_bound_items) in
-  { expansion }
+  { expansion; doc }
 #endif
 
 and read_signature :

src/model/lang.ml

@@ -156,7 +156,7 @@ end =
   Signature
 
 and Open : sig
-  type t = { expansion : Signature.t }
+  type t = { expansion : Signature.t; doc : Comment.docs }
 end =
   Open
 

src/xref2/component.ml

@@ -327,7 +327,7 @@ end =
   Signature
 
 and Open : sig
-  type t = { expansion : Signature.t }
+  type t = { expansion : Signature.t; doc : CComment.docs }
 end =
   Open
 
@@ -2331,7 +2331,10 @@ module Of_Lang = struct
 
   and open_ ident_map o =
     Open.
-      { expansion = apply_sig_map ident_map o.Odoc_model.Lang.Open.expansion }
+      {
+        expansion = apply_sig_map ident_map o.Odoc_model.Lang.Open.expansion;
+        doc = docs ident_map o.Odoc_model.Lang.Open.doc;
+      }
 
   and apply_sig_map ident_map sg =
     let items =

src/xref2/component.mli

@@ -299,7 +299,7 @@ and Signature : sig
 end
 
 and Open : sig
-  type t = { expansion : Signature.t }
+  type t = { expansion : Signature.t; doc : CComment.docs }
 end
 
 and Include : sig

src/xref2/env.ml

@@ -740,8 +740,10 @@ let rec open_signature : Odoc_model.Lang.Signature.t -> t -> t =
             let ty = class_type empty c in
             add_class_type c.id ty env
         | L.Signature.Include i, _ -> open_signature i.expansion.content env
-        | L.Signature.Open o, _ -> open_signature o.expansion env
+        | L.Signature.Open o, false -> open_signature o.expansion env
         (* The following are only added when linking *)
+        | L.Signature.Open o, true ->
+            add_comment (`Docs o.doc) (open_signature o.expansion env)
         | Comment c, true -> add_comment c env
         | TypExt te, true ->
             let doc = docs empty te.doc in

src/xref2/lang_of.ml

@@ -618,7 +618,10 @@ and include_ parent map i =
 
 and open_ parent map o =
   let open Component.Open in
-  { Odoc_model.Lang.Open.expansion = signature parent map o.expansion }
+  {
+    Odoc_model.Lang.Open.expansion = signature parent map o.expansion;
+    doc = docs (parent :> Identifier.LabelParent.t) o.doc;
+  }
 
 and value_ map parent id v =
   let open Component.Value in

src/xref2/link.ml

@@ -246,6 +246,10 @@ and comment env parent = function
   | `Stop -> `Stop
   | `Docs d -> `Docs (comment_docs env parent d)
 
+and open_ env parent = function
+  | { Odoc_model__Lang.Open.doc; _ } as open_ ->
+      { open_ with doc = comment_docs env parent doc }
+
 let rec unit env t =
   let open Compilation_unit in
   let content =
@@ -370,7 +374,7 @@ and signature_items :
       | Class (r, c) -> Class (r, class_ env id c)
       | ClassType (r, c) -> ClassType (r, class_type env id c)
       | Include i -> Include (include_ env i)
-      | Open o -> Open o)
+      | Open o -> Open (open_ env id o))
     s
 
 and simple_expansion :

src/xref2/subst.ml

@@ -846,7 +846,7 @@ and include_ s i =
 
 and open_ s o =
   let open Component.Open in
-  { expansion = apply_sig_map_sg s o.expansion }
+  { expansion = apply_sig_map_sg s o.expansion; doc = o.doc }
 
 and value s v =
   let open Component.Value in
@@ -1017,10 +1017,10 @@ and rename_bound_idents s sg =
         (Include { i with expansion_ = { expansion_ with items; removed = [] } }
         :: sg)
         rest
-  | Open { expansion } :: rest ->
+  | Open { expansion; doc } :: rest ->
       let s, items = rename_bound_idents s [] expansion.items in
       rename_bound_idents s
-        (Open { expansion = { expansion with items; removed = [] } } :: sg)
+        (Open { expansion = { expansion with items; removed = [] }; doc } :: sg)
         rest
   | (Comment _ as item) :: rest -> rename_bound_idents s (item :: sg) rest
 

test/generators/cases/toplevel_comments.mli

@@ -79,3 +79,16 @@ module Ref_in_synopsis : sig
 
   type t
 end
+
+module Comments_on_open : sig
+  module M : sig
+    type t
+  end
+
+  open M
+      (** 
+          {2:sec Section}
+
+          Comments attached to open are treated as floating comments.
+         Referencing {!section-sec} {!M.t} works *)
+end

test/generators/html/Toplevel_comments-Comments_on_open-M.html

@@ -0,0 +1,29 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head><title>M (Toplevel_comments.Comments_on_open.M)</title>
+  <link rel="stylesheet" href="odoc.css"/><meta charset="utf-8"/>
+  <meta name="generator" content="odoc %%VERSION%%"/>
+  <meta name="viewport" content="width=device-width,initial-scale=1.0"/>
+  <script src="highlight.pack.js"></script>
+  <script>hljs.initHighlightingOnLoad();</script>
+ </head>
+ <body class="odoc">
+  <nav class="odoc-nav">
+   <a href="Toplevel_comments-Comments_on_open.html">Up</a> – 
+   <a href="Toplevel_comments.html">Toplevel_comments</a> &#x00BB; 
+   <a href="Toplevel_comments-Comments_on_open.html">Comments_on_open</a>
+    &#x00BB; M
+  </nav>
+  <header class="odoc-preamble">
+   <h1>Module <code><span>Comments_on_open.M</span></code></h1>
+  </header>
+  <div class="odoc-content">
+   <div class="odoc-spec">
+    <div class="spec type" id="type-t" class="anchored">
+     <a href="#type-t" class="anchor"></a>
+     <code><span><span class="keyword">type</span> t</span></code>
+    </div>
+   </div>
+  </div>
+ </body>
+</html>

test/generators/html/Toplevel_comments-Comments_on_open.html

@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head><title>Comments_on_open (Toplevel_comments.Comments_on_open)</title>
+  <link rel="stylesheet" href="odoc.css"/><meta charset="utf-8"/>
+  <meta name="generator" content="odoc %%VERSION%%"/>
+  <meta name="viewport" content="width=device-width,initial-scale=1.0"/>
+  <script src="highlight.pack.js"></script>
+  <script>hljs.initHighlightingOnLoad();</script>
+ </head>
+ <body class="odoc">
+  <nav class="odoc-nav"><a href="Toplevel_comments.html">Up</a> – 
+   <a href="Toplevel_comments.html">Toplevel_comments</a> &#x00BB; 
+   Comments_on_open
+  </nav>
+  <header class="odoc-preamble">
+   <h1>Module <code><span>Toplevel_comments.Comments_on_open</span></code>
+   </h1>
+  </header>
+  <nav class="odoc-toc"><ul><li><a href="#sec">Section</a></li></ul></nav>
+  <div class="odoc-content">
+   <div class="odoc-spec">
+    <div class="spec module" id="module-M" class="anchored">
+     <a href="#module-M" class="anchor"></a>
+     <code>
+      <span><span class="keyword">module</span> 
+       <a href="Toplevel_comments-Comments_on_open-M.html">M</a>
+      </span>
+      <span> : <span class="keyword">sig</span> ... 
+       <span class="keyword">end</span>
+      </span>
+     </code>
+    </div>
+   </div><h3 id="sec"><a href="#sec" class="anchor"></a>Section</h3>
+   <p>Comments attached to open are treated as floating comments. Referencing
+     <a href="#sec">Section</a> 
+    <a href="Toplevel_comments-Comments_on_open-M.html#type-t">
+     <code>M.t</code>
+    </a> works
+   </p>
+  </div>
+ </body>
+</html>

test/generators/html/Toplevel_comments.html

@@ -199,6 +199,19 @@ <h1>Module <code><span>Toplevel_comments</span></code></h1>
      </p>
     </div>
    </div>
+   <div class="odoc-spec">
+    <div class="spec module" id="module-Comments_on_open" class="anchored">
+     <a href="#module-Comments_on_open" class="anchor"></a>
+     <code>
+      <span><span class="keyword">module</span> 
+       <a href="Toplevel_comments-Comments_on_open.html">Comments_on_open</a>
+      </span>
+      <span> : <span class="keyword">sig</span> ... 
+       <span class="keyword">end</span>
+      </span>
+     </code>
+    </div>
+   </div>
   </div>
  </body>
 </html>

test/generators/html/toplevel_comments.targets

@@ -12,3 +12,5 @@ Toplevel_comments-class-c1.html
 Toplevel_comments-class-type-ct.html
 Toplevel_comments-class-c2.html
 Toplevel_comments-Ref_in_synopsis.html
+Toplevel_comments-Comments_on_open.html
+Toplevel_comments-Comments_on_open-M.html

test/generators/latex/Toplevel_comments.tex

@@ -43,6 +43,14 @@ \section{Module \ocamlinlinecode{Toplevel\_\allowbreak{}comments}}\label{module-
 \end{ocamlindent}%
 \ocamlcodefragment{\ocamltag{keyword}{end}}\begin{ocamlindent}\hyperref[module-Toplevel+u+comments-module-Ref+u+in+u+synopsis-type-t]{\ocamlinlinecode{\ocamlinlinecode{t}}[p\pageref*{module-Toplevel+u+comments-module-Ref+u+in+u+synopsis-type-t}]}.\end{ocamlindent}%
 \medbreak
+\label{module-Toplevel+u+comments-module-Comments+u+on+u+open}\ocamlcodefragment{\ocamltag{keyword}{module} \hyperref[module-Toplevel+u+comments-module-Comments+u+on+u+open]{\ocamlinlinecode{Comments\_\allowbreak{}on\_\allowbreak{}open}}}\ocamlcodefragment{ : \ocamltag{keyword}{sig}}\begin{ocamlindent}\label{module-Toplevel+u+comments-module-Comments+u+on+u+open-module-M}\ocamlcodefragment{\ocamltag{keyword}{module} \hyperref[module-Toplevel+u+comments-module-Comments+u+on+u+open-module-M]{\ocamlinlinecode{M}}}\ocamlcodefragment{ : \ocamltag{keyword}{sig}}\begin{ocamlindent}\label{module-Toplevel+u+comments-module-Comments+u+on+u+open-module-M-type-t}\ocamlcodefragment{\ocamltag{keyword}{type} t}\\
+\end{ocamlindent}%
+\ocamlcodefragment{\ocamltag{keyword}{end}}\\
+\subsubsection{Section\label{sec}}%
+Comments attached to open are treated as floating comments. Referencing \hyperref[module-Toplevel+u+comments-module-Comments+u+on+u+open-sec]{\ocamlinlinecode{Section}[p\pageref*{module-Toplevel+u+comments-module-Comments+u+on+u+open-sec}]} \hyperref[module-Toplevel+u+comments-module-Comments+u+on+u+open-module-M-type-t]{\ocamlinlinecode{\ocamlinlinecode{M.\allowbreak{}t}}[p\pageref*{module-Toplevel+u+comments-module-Comments+u+on+u+open-module-M-type-t}]} works
+
+\end{ocamlindent}%
+\ocamlcodefragment{\ocamltag{keyword}{end}}\\
 
 \input{Toplevel_comments.Alias.tex}
 \input{Toplevel_comments.c1.tex}

test/generators/link.dune.inc

@@ -6161,7 +6161,9 @@
    Toplevel_comments-class-c1.html.gen
    Toplevel_comments-class-type-ct.html.gen
    Toplevel_comments-class-c2.html.gen
-   Toplevel_comments-Ref_in_synopsis.html.gen)
+   Toplevel_comments-Ref_in_synopsis.html.gen
+   Toplevel_comments-Comments_on_open.html.gen
+   Toplevel_comments-Comments_on_open-M.html.gen)
   (action
    (run
     odoc
@@ -6242,7 +6244,19 @@
   (action
    (diff
     Toplevel_comments-Ref_in_synopsis.html
-    Toplevel_comments-Ref_in_synopsis.html.gen))))
+    Toplevel_comments-Ref_in_synopsis.html.gen)))
+ (rule
+  (alias runtest)
+  (action
+   (diff
+    Toplevel_comments-Comments_on_open.html
+    Toplevel_comments-Comments_on_open.html.gen)))
+ (rule
+  (alias runtest)
+  (action
+   (diff
+    Toplevel_comments-Comments_on_open-M.html
+    Toplevel_comments-Comments_on_open-M.html.gen))))
 
 (subdir
  html
@@ -6315,7 +6329,9 @@
    Toplevel_comments.Alias.3o.gen
    Toplevel_comments.c1.3o.gen
    Toplevel_comments.c2.3o.gen
-   Toplevel_comments.Ref_in_synopsis.3o.gen)
+   Toplevel_comments.Ref_in_synopsis.3o.gen
+   Toplevel_comments.Comments_on_open.3o.gen
+   Toplevel_comments.Comments_on_open.M.3o.gen)
   (action
    (run
     odoc
@@ -6370,7 +6386,19 @@
   (action
    (diff
     Toplevel_comments.Ref_in_synopsis.3o
-    Toplevel_comments.Ref_in_synopsis.3o.gen))))
+    Toplevel_comments.Ref_in_synopsis.3o.gen)))
+ (rule
+  (alias runtest)
+  (action
+   (diff
+    Toplevel_comments.Comments_on_open.3o
+    Toplevel_comments.Comments_on_open.3o.gen)))
+ (rule
+  (alias runtest)
+  (action
+   (diff
+    Toplevel_comments.Comments_on_open.M.3o
+    Toplevel_comments.Comments_on_open.M.3o.gen))))
 
 (subdir
  man

test/generators/man/Toplevel_comments.3o

@@ -119,4 +119,5 @@ Doc of c2\.
 .ti +2
 \f[CI]t\fR\.
 .nf 
-
+.sp 
+\f[CB]module\fR Comments_on_open : \f[CB]sig\fR \.\.\. \f[CB]end\fR

test/generators/man/Toplevel_comments.Comments_on_open.3o

@@ -0,0 +1,23 @@
+
+.TH Comments_on_open 3 "" "Odoc" "OCaml Library"
+.SH Name
+Toplevel_comments\.Comments_on_open
+.SH Synopsis
+.sp 
+.in 2
+\fBModule Toplevel_comments\.Comments_on_open\fR
+.in 
+.sp 
+.SH Documentation
+.sp 
+.nf 
+\f[CB]module\fR M : \f[CB]sig\fR \.\.\. \f[CB]end\fR
+.sp 
+.in 4
+\fB1\.1 Section\fR
+.in 
+.sp 
+.fi 
+Comments attached to open are treated as floating comments\. Referencing \f[CI]Section\fR \f[CI]M\.t\fR works
+.nf 
+

test/generators/man/Toplevel_comments.Comments_on_open.M.3o

@@ -0,0 +1,14 @@
+
+.TH M 3 "" "Odoc" "OCaml Library"
+.SH Name
+Toplevel_comments\.Comments_on_open\.M
+.SH Synopsis
+.sp 
+.in 2
+\fBModule Comments_on_open\.M\fR
+.in 
+.sp 
+.SH Documentation
+.sp 
+.nf 
+\f[CB]type\fR t