From 498ced7705220d649281537632fc94c6fea5f6b2 Mon Sep 17 00:00:00 2001 From: Paul-Elliot Date: Mon, 13 Dec 2021 17:02:02 +0100 Subject: [PATCH 1/3] quick-fix, to check Signed-off-by: Paul-Elliot --- src/document/generator.ml | 4 +++- src/loader/cmt.ml | 4 +++- src/loader/cmti.ml | 4 +++- src/model/lang.ml | 2 +- src/xref2/component.ml | 7 +++++-- src/xref2/component.mli | 2 +- src/xref2/lang_of.ml | 5 ++++- src/xref2/subst.ml | 6 +++--- 8 files changed, 23 insertions(+), 11 deletions(-) diff --git a/src/document/generator.ml b/src/document/generator.ml index 8bb05eaa2b..e4fdc41442 100644 --- a/src/document/generator.ml +++ b/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 diff --git a/src/loader/cmt.ml b/src/loader/cmt.ml index 643e18557f..e206608467 100644 --- a/src/loader/cmt.ml +++ b/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 : diff --git a/src/loader/cmti.ml b/src/loader/cmti.ml index 14d526993d..bf66c6d5e3 100644 --- a/src/loader/cmti.ml +++ b/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 : diff --git a/src/model/lang.ml b/src/model/lang.ml index 4670ac359f..498264585c 100644 --- a/src/model/lang.ml +++ b/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 diff --git a/src/xref2/component.ml b/src/xref2/component.ml index c341a9007c..e1e551c6df 100644 --- a/src/xref2/component.ml +++ b/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 = diff --git a/src/xref2/component.mli b/src/xref2/component.mli index d6e5959bb3..7d4f07efaf 100644 --- a/src/xref2/component.mli +++ b/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 diff --git a/src/xref2/lang_of.ml b/src/xref2/lang_of.ml index 21f0aff40e..ce0fa6928b 100644 --- a/src/xref2/lang_of.ml +++ b/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 diff --git a/src/xref2/subst.ml b/src/xref2/subst.ml index 548576de8f..7a21f37228 100644 --- a/src/xref2/subst.ml +++ b/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 From f2be8f24ffe6f03f773756e6c28a94836f043457 Mon Sep 17 00:00:00 2001 From: Paul-Elliot Date: Tue, 14 Dec 2021 10:00:23 +0100 Subject: [PATCH 2/3] adding missing linking parts Signed-off-by: Paul-Elliot --- src/xref2/env.ml | 4 +++- src/xref2/link.ml | 6 +++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/src/xref2/env.ml b/src/xref2/env.ml index 5075c9bdb8..73302c9a75 100644 --- a/src/xref2/env.ml +++ b/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 diff --git a/src/xref2/link.ml b/src/xref2/link.ml index b6d804e3b6..ac5ecfa09f 100644 --- a/src/xref2/link.ml +++ b/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 : From bc5449e1b52a872fba2ffb076f293a8128f7ee10 Mon Sep 17 00:00:00 2001 From: Paul-Elliot Date: Tue, 14 Dec 2021 12:09:17 +0100 Subject: [PATCH 3/3] Adding tests and changelog entry Signed-off-by: Paul-Elliot --- CHANGES.md | 4 ++ test/generators/cases/toplevel_comments.mli | 13 ++++++ .../Toplevel_comments-Comments_on_open-M.html | 29 +++++++++++++ .../Toplevel_comments-Comments_on_open.html | 42 +++++++++++++++++++ test/generators/html/Toplevel_comments.html | 13 ++++++ .../generators/html/toplevel_comments.targets | 2 + test/generators/latex/Toplevel_comments.tex | 8 ++++ test/generators/link.dune.inc | 36 ++++++++++++++-- test/generators/man/Toplevel_comments.3o | 3 +- .../man/Toplevel_comments.Comments_on_open.3o | 23 ++++++++++ .../Toplevel_comments.Comments_on_open.M.3o | 14 +++++++ test/generators/man/toplevel_comments.targets | 2 + 12 files changed, 184 insertions(+), 5 deletions(-) create mode 100644 test/generators/html/Toplevel_comments-Comments_on_open-M.html create mode 100644 test/generators/html/Toplevel_comments-Comments_on_open.html create mode 100644 test/generators/man/Toplevel_comments.Comments_on_open.3o create mode 100644 test/generators/man/Toplevel_comments.Comments_on_open.M.3o diff --git a/CHANGES.md b/CHANGES.md index 76f69d3335..c1e256b9f2 100644 --- a/CHANGES.md +++ b/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 ----- diff --git a/test/generators/cases/toplevel_comments.mli b/test/generators/cases/toplevel_comments.mli index 342a884c87..ad74dab9b8 100644 --- a/test/generators/cases/toplevel_comments.mli +++ b/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 diff --git a/test/generators/html/Toplevel_comments-Comments_on_open-M.html b/test/generators/html/Toplevel_comments-Comments_on_open-M.html new file mode 100644 index 0000000000..64c15f9761 --- /dev/null +++ b/test/generators/html/Toplevel_comments-Comments_on_open-M.html @@ -0,0 +1,29 @@ + + + M (Toplevel_comments.Comments_on_open.M) + + + + + + + + +
+

Module Comments_on_open.M

+
+
+
+
+ + type t +
+
+
+ + \ No newline at end of file diff --git a/test/generators/html/Toplevel_comments-Comments_on_open.html b/test/generators/html/Toplevel_comments-Comments_on_open.html new file mode 100644 index 0000000000..e317cbc6e8 --- /dev/null +++ b/test/generators/html/Toplevel_comments-Comments_on_open.html @@ -0,0 +1,42 @@ + + + Comments_on_open (Toplevel_comments.Comments_on_open) + + + + + + + + +
+

Module Toplevel_comments.Comments_on_open +

+
+ +
+
+
+ + + module + M + + : sig ... + end + + +
+

Section

+

Comments attached to open are treated as floating comments. Referencing + Section + + M.t + works +

+
+ + \ No newline at end of file diff --git a/test/generators/html/Toplevel_comments.html b/test/generators/html/Toplevel_comments.html index b71979456d..99746fe19a 100644 --- a/test/generators/html/Toplevel_comments.html +++ b/test/generators/html/Toplevel_comments.html @@ -199,6 +199,19 @@

Module Toplevel_comments

+
+
+ + + module + Comments_on_open + + : sig ... + end + + +
+
\ No newline at end of file diff --git a/test/generators/html/toplevel_comments.targets b/test/generators/html/toplevel_comments.targets index 648430d265..1e17e49dbb 100644 --- a/test/generators/html/toplevel_comments.targets +++ b/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 diff --git a/test/generators/latex/Toplevel_comments.tex b/test/generators/latex/Toplevel_comments.tex index 6c031c7bd6..83d43a0b18 100644 --- a/test/generators/latex/Toplevel_comments.tex +++ b/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} diff --git a/test/generators/link.dune.inc b/test/generators/link.dune.inc index 467b672393..0a80c76332 100644 --- a/test/generators/link.dune.inc +++ b/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 diff --git a/test/generators/man/Toplevel_comments.3o b/test/generators/man/Toplevel_comments.3o index 9ee9a0b7cf..8241e17abf 100644 --- a/test/generators/man/Toplevel_comments.3o +++ b/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 diff --git a/test/generators/man/Toplevel_comments.Comments_on_open.3o b/test/generators/man/Toplevel_comments.Comments_on_open.3o new file mode 100644 index 0000000000..17d04cb2fa --- /dev/null +++ b/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 + diff --git a/test/generators/man/Toplevel_comments.Comments_on_open.M.3o b/test/generators/man/Toplevel_comments.Comments_on_open.M.3o new file mode 100644 index 0000000000..8538648814 --- /dev/null +++ b/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 diff --git a/test/generators/man/toplevel_comments.targets b/test/generators/man/toplevel_comments.targets index ea2909b1c5..0123faa972 100644 --- a/test/generators/man/toplevel_comments.targets +++ b/test/generators/man/toplevel_comments.targets @@ -8,3 +8,5 @@ Toplevel_comments.Alias.3o Toplevel_comments.c1.3o Toplevel_comments.c2.3o Toplevel_comments.Ref_in_synopsis.3o +Toplevel_comments.Comments_on_open.3o +Toplevel_comments.Comments_on_open.M.3o