Skip to content

Don't remove the doc of inline includes #595

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Feb 26, 2021
Merged

Don't remove the doc of inline includes #595

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d061618
test/html: Improve promoting
Julow Feb 19, 2021
fb2c379
test/html: Fix escaping of filenames containing '
Julow Feb 19, 2021
6fbfdbd
Add tests for inline includes
Julow Feb 19, 2021
95237ca
Don't remove the doc of @inline include expansions
Julow Feb 22, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -159,3 +159,9 @@ uutf/dune-project : uutf
.PHONY : distclean
distclean :
rm -rf $(DUNIVERSE_DEPS) dune-local

.PHONY : promote-html
promote-html:
EXPECTED=`cat _build/default/test/html/_scratch/expected`; \
ACTUAL=`cat _build/default/test/html/_scratch/actual`; \
mkdir -p "`dirname "$$EXPECTED"`" && cp "$$ACTUAL" "$$EXPECTED"
8 changes: 1 addition & 7 deletions src/xref2/compile.ml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -308,11 +308,6 @@ and module_type : Env.t -> ModuleType.t -> ModuleType.t =
and include_ : Env.t -> Include.t -> Include.t =
fun env i ->
let open Include in
let remove_top_doc_from_signature s =
let open Signature in
let items = match s.items with Comment (`Docs _) :: xs -> xs | xs -> xs in
{ s with items }
in
let decl = Component.Of_Lang.(include_decl empty i.decl) in
let get_expansion () =
match
Expand All @@ -339,8 +334,7 @@ and include_ : Env.t -> Include.t -> Include.t =
in
{
shadowed = i.expansion.shadowed;
content =
remove_top_doc_from_signature (signature env i.parent expansion_sg);
content = signature env i.parent expansion_sg;
}
in
let expansion =
Expand Down
31 changes: 16 additions & 15 deletions src/xref2/link.ml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,11 @@ let synopsis_from_comment docs =
| _ -> None)
docs

let remove_top_doc_from_signature s =
let open Signature in
let items = match s.items with Comment (`Docs _) :: xs -> xs | xs -> xs in
{ s with items }

exception Loop

let rec is_forward : Paths.Path.Module.t -> bool = function
Expand Down Expand Up @@ -417,14 +422,12 @@ and module_ : Env.t -> Module.t -> Module.t =
Alias (`Resolved p, Some (simple_expansion env sg_id le))
| Error _ -> Alias (`Resolved p, e)
else Alias (`Resolved p, e)
| Alias _ -> type_
| ModuleType mty -> ModuleType mty
| Alias _ | ModuleType _ -> type_
in
let doc, type_ =
match m.doc with [] -> extract_doc type_ | _ -> (m.doc, type_)
in
let result = { m with doc = comment_docs env doc; type_ } in
result
{ m with doc = comment_docs env doc; type_ }

and module_decl : Env.t -> Id.Signature.t -> Module.decl -> Module.decl =
fun env id decl ->
Expand Down Expand Up @@ -470,17 +473,15 @@ and include_ : Env.t -> Include.t -> Include.t =
let is_inline_tag element = element.Location_.value = `Tag `Inline in
List.exists is_inline_tag doc
in
{
i with
decl;
expansion =
{
shadowed = i.expansion.shadowed;
content = signature env i.parent i.expansion.content;
};
inline = should_be_inlined;
doc;
}
let expansion =
let content = signature env i.parent i.expansion.content in
let content =
if should_be_inlined then content
else remove_top_doc_from_signature content
in
{ i.expansion with content }
in
{ i with decl; expansion; inline = should_be_inlined; doc }

and functor_parameter_parameter :
Env.t -> FunctorParameter.parameter -> FunctorParameter.parameter =
Expand Down
37 changes: 37 additions & 0 deletions test/cases/toplevel_comments.mli
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
(** A doc comment at the beginning of a module is considered to be that
module's doc. *)

(** Doc of [T], part 1. *)
module type T = sig
(** Doc of [T], part 2. *)

type t
end

module Include_inline : sig
include T
(** @inline *)
end

(** Doc of [Include_inline], part 1. *)
module Include_inline' : sig
(** Doc of [Include_inline], part 2. *)

include T
(** part 3
@inline *)
end

module type Include_inline_T = sig
include T
(** @inline *)
end

(** Doc of [Include_inline_T'], part 1. *)
module type Include_inline_T' = sig
(** Doc of [Include_inline_T'], part 2. *)

include T
(** part 3
@inline *)
end
51 changes: 51 additions & 0 deletions test/html/expect/test_package+ml/Toplevel_comments/Include_inline'/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>
Include_inline' (test_package+ml.Toplevel_comments.Include_inline')
</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="../index.html">Up</a> – <a href="../../index.html">test_package+ml</a> » <a href="../index.html">Toplevel_comments</a> » Include_inline'
</nav>
<header class="odoc-preamble">
<h1>
Module <code><span>Toplevel_comments.Include_inline'</span></code>
</h1>
<p>
Doc of <code>Include_inline</code>, part 1.
</p>
</header>
<div class="odoc-content">
<p>
Doc of <code>Include_inline</code>, part 2.
</p>
<div class="odoc-include">
<div class="spec include">
<div class="doc">
<p>
part 3
</p>
<p>
Doc of <code>T</code>, part 2.
</p>
<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>
</div>
</div>
</div>
</div>
</div>
</div>
</body>
</html>
42 changes: 42 additions & 0 deletions test/html/expect/test_package+ml/Toplevel_comments/Include_inline/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>
Include_inline (test_package+ml.Toplevel_comments.Include_inline)
</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="../index.html">Up</a> – <a href="../../index.html">test_package+ml</a> » <a href="../index.html">Toplevel_comments</a> » Include_inline
</nav>
<header class="odoc-preamble">
<h1>
Module <code><span>Toplevel_comments.Include_inline</span></code>
</h1>
</header>
<div class="odoc-content">
<div class="odoc-include">
<div class="spec include">
<div class="doc">
<p>
Doc of <code>T</code>, part 2.
</p>
<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>
</div>
</div>
</div>
</div>
</div>
</div>
</body>
</html>
71 changes: 71 additions & 0 deletions test/html/expect/test_package+ml/Toplevel_comments/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>
Toplevel_comments (test_package+ml.Toplevel_comments)
</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="../index.html">Up</a> – <a href="../index.html">test_package+ml</a> » Toplevel_comments
</nav>
<header class="odoc-preamble">
<h1>
Module <code><span>Toplevel_comments</span></code>
</h1>
<p>
A doc comment at the beginning of a module is considered to be that module's doc.
</p>
</header>
<div class="odoc-content">
<div class="odoc-spec">
<div class="spec module-type" id="module-type-T">
<a href="#module-type-T" class="anchor"></a><code><span><span class="keyword">module</span> <span class="keyword">type</span> </span><span><a href="module-type-T/index.html">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 1.
</p>
</div>
</div>
<div class="odoc-spec">
<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>
<div class="odoc-spec">
<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>Include_inline</code>, part 1.
</p>
</div>
</div>
<div class="odoc-spec">
<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>
<div class="odoc-spec">
<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>Include_inline_T'</code>, part 1.
</p>
</div>
</div>
</div>
</body>
</html>
51 changes: 51 additions & 0 deletions test/html/expect/test_package+ml/Toplevel_comments/module-type-Include_inline_T'/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>
Include_inline_T' (test_package+ml.Toplevel_comments.Include_inline_T')
</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="../index.html">Up</a> – <a href="../../index.html">test_package+ml</a> » <a href="../index.html">Toplevel_comments</a> » Include_inline_T'
</nav>
<header class="odoc-preamble">
<h1>
Module type <code><span>Toplevel_comments.Include_inline_T'</span></code>
</h1>
<p>
Doc of <code>Include_inline_T'</code>, part 1.
</p>
</header>
<div class="odoc-content">
<p>
Doc of <code>Include_inline_T'</code>, part 2.
</p>
<div class="odoc-include">
<div class="spec include">
<div class="doc">
<p>
part 3
</p>
<p>
Doc of <code>T</code>, part 2.
</p>
<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>
</div>
</div>
</div>
</div>
</div>
</div>
</body>
</html>
42 changes: 42 additions & 0 deletions test/html/expect/test_package+ml/Toplevel_comments/module-type-Include_inline_T/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>
Include_inline_T (test_package+ml.Toplevel_comments.Include_inline_T)
</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="../index.html">Up</a> – <a href="../../index.html">test_package+ml</a> » <a href="../index.html">Toplevel_comments</a> » Include_inline_T
</nav>
<header class="odoc-preamble">
<h1>
Module type <code><span>Toplevel_comments.Include_inline_T</span></code>
</h1>
</header>
<div class="odoc-content">
<div class="odoc-include">
<div class="spec include">
<div class="doc">
<p>
Doc of <code>T</code>, part 2.
</p>
<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>
</div>
</div>
</div>
</div>
</div>
</div>
</body>
</html>
Loading