Skip to content

Render documentation attached to includes #647

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.

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 3 commits into from
Apr 6, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
11 changes: 9 additions & 2 deletions src/document/generator.ml
Original file line number Diff line number Diff line change
Expand Up @@ -1536,7 +1536,7 @@ module Make (Syntax : SYNTAX) = struct
| ModuleType mt -> umty mt
in

let sg_doc, content = signature t.expansion.content in
let _, content = signature t.expansion.content in
let summary =
O.render
(O.keyword "include" ++ O.txt " " ++ include_decl
Expand All @@ -1545,7 +1545,14 @@ module Make (Syntax : SYNTAX) = struct
let content = { Include.content; status; summary } in
let attr = [ "include" ] in
let anchor = None in
let doc = Comment.synopsis ~decl_doc:[] ~expansion_doc:(Some sg_doc) in
let doc =
(* Documentation attached to includes behave differently than other
declarations, which show only the synopsis. We can't only show the
synopsis because no page is generated to render it and we'd loose
the full documentation.
The documentation from the expansion is not used. *)
Comment.to_ir t.doc
in
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is first_to_ir still use after that ?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, it's removed.

Item.Include { attr; anchor; doc; content }
end

Expand Down
17 changes: 17 additions & 0 deletions test/cases/include2.ml
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,20 @@ end

include X

module Y = struct
(** Top-comment of Y. *)

type t
end

module Y_include_synopsis = struct
(** The [include Y] below should have the synopsis from [Y]'s top-comment
attached to it. *)

include Y
end

module Y_include_doc = struct
include Y
(** Doc attached to [include Y]. [Y]'s top-comment shouldn't appear here. *)
end
45 changes: 45 additions & 0 deletions test/html/expect/test_package+ml/Include2/Y_include_doc/index.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>
Y_include_doc (test_package+ml.Include2.Y_include_doc)
</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">Include2</a> » Y_include_doc
</nav>
<header class="odoc-preamble">
<h1>
Module <code><span>Include2.Y_include_doc</span></code>
</h1>
</header>
<div class="odoc-content">
<div class="odoc-include">
<div class="spec-doc">
<p>
Doc attached to <code>include Y</code>. <code>Y</code>'s top-comment shouldn't appear here.
</p>
</div>
<details open="open">
<summary class="spec include">
<code><span><span class="keyword">include</span> <span class="keyword">module</span> <span class="keyword">type</span> <span class="keyword">of</span> <span class="keyword">struct</span> <span class="keyword">include</span> <a href="../Y/index.html">Y</a> <span class="keyword">end</span></span></code>
</summary>
<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><span> = <a href="../Y/index.html#type-t">Y.t</a></span></code>
</div>
</div>
</details>
</div>
</div>
</body>
</html>
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>
Y_include_synopsis (test_package+ml.Include2.Y_include_synopsis)
</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">Include2</a> » Y_include_synopsis
</nav>
<header class="odoc-preamble">
<h1>
Module <code><span>Include2.Y_include_synopsis</span></code>
</h1>
<p>
The <code>include Y</code> below should have the synopsis from <code>Y</code>'s top-comment attached to it.
</p>
</header>
<div class="odoc-content">
<div class="odoc-include">
<details open="open">
<summary class="spec include">
<code><span><span class="keyword">include</span> <span class="keyword">module</span> <span class="keyword">type</span> <span class="keyword">of</span> <span class="keyword">struct</span> <span class="keyword">include</span> <a href="../Y/index.html">Y</a> <span class="keyword">end</span></span></code>
</summary>
<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><span> = <a href="../Y/index.html#type-t">Y.t</a></span></code>
</div>
</div>
</details>
</div>
</div>
</body>
</html>
25 changes: 25 additions & 0 deletions test/html/expect/test_package+ml/Include2/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,31 @@ <h1>
</div>
</details>
</div>
<div class="odoc-spec">
<div class="spec module" id="module-Y">
<a href="#module-Y" class="anchor"></a><code><span><span class="keyword">module</span> </span><span><a href="Y/index.html">Y</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code>
</div>
<div class="spec-doc">
<p>
Top-comment of Y.
</p>
</div>
</div>
<div class="odoc-spec">
<div class="spec module" id="module-Y_include_synopsis">
<a href="#module-Y_include_synopsis" class="anchor"></a><code><span><span class="keyword">module</span> </span><span><a href="Y_include_synopsis/index.html">Y_include_synopsis</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code>
</div>
<div class="spec-doc">
<p>
The <code>include Y</code> below should have the synopsis from <code>Y</code>'s top-comment attached to it.
</p>
</div>
</div>
<div class="odoc-spec">
<div class="spec module" id="module-Y_include_doc">
<a href="#module-Y_include_doc" class="anchor"></a><code><span><span class="keyword">module</span> </span><span><a href="Y_include_doc/index.html">Y_include_doc</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code>
</div>
</div>
</div>
</body>
</html>
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ <h1>
<div class="odoc-include">
<div class="spec-doc">
<p>
Doc of <code>T</code>, part 2.
part 3
</p>
</div>
<div class="odoc-spec">
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,11 +24,6 @@ <h1>
</header>
<div class="odoc-content">
<div class="odoc-include">
<div class="spec-doc">
<p>
Doc of <code>T</code>, part 2.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is removed because there is a documentation attached but it renders to nothing.
Some elements don't render to anything, for example @inline tags.

We could decide it's fine or we could add an exception for for elements that do not render ? cc @dbuenzli

Unrelated thought: Should we handle tags specifically ?
Currently, it's possible to have tags in the middle of a comment or in the middle of the preamble.
I don't see tags as markup elements like headings and paragraphs but as metadata attached directly to the declarations. I'd expect them on the same hierarchical level as the documentation text, not inside it.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could decide it's fine or we could add an exception for for elements that do not render ? cc @dbuenzli

I don't understand the question. Also:

Now, the attached documentation is rendered entirely and the includee top-comment is not.

The top-comment may already have docs, e.g. headings and paragraphs, I think you want these rendered. Did you want to say that you drop the preamble ?

I don't want to sound like a broken record but I think the only way to get to a consistent system is to think about these things in terms of synopse, preamble and content, not in terms of comments.

I don't see tags as markup elements like headings and paragraphs but as metadata attached directly to the declarations. I'd expect them on the same hierarchical level as the documentation text, not inside it.

That would be my understanding as well. But:

I don't see tags as markup elements like headings and paragraphs but as metadata attached directly to the declarations.

They are still placed by end-users as they see it fit so I think we should consider them as block-level stuff (and consecutive sequences of tags should define a single block, not done yet see #607)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On a regular declaration the preamble would be the tag then the paragraph but we agreed in #645 that includes are different, there is no preamble ever generated, we either take the decl comment entirely or make a synopsis from T's top-comment.

The problem I'm mentioning is that in this case:

module type T = sig
  (** Top-comment of T. *)
end

include T
(** @inline *)

the decl comment renders to nothing but is not technically empty so we won't attempt to take the synopsis out of T. Potential fixes:

  • Decide it's OK
  • Consider tags targeted at Odoc are not part of the doc (they are not rendered currently but are part of the markup: canonical, inline, open, closed)
  • Handle tags at a different level and render them separately (eg. always after the documentation, wherever they are placed by the user). Like the previous point but applies to every tags and changes the layout.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Consider tags targeted at Odoc are not part of the doc (they are not rendered currently but are part of the markup: canonical, inline, open, closed)

Ah yes thanks for the clarifification. I'd say that this is the right idea.

</p>
</div>
<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>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ <h1>
<div class="odoc-include">
<div class="spec-doc">
<p>
Doc of <code>T</code>, part 2.
part 3
</p>
</div>
<div class="odoc-spec">
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,11 +24,6 @@ <h1>
</header>
<div class="odoc-content">
<div class="odoc-include">
<div class="spec-doc">
<p>
Doc of <code>T</code>, part 2.
</p>
</div>
<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>
Expand Down
45 changes: 45 additions & 0 deletions test/html/expect/test_package+re/Include2/Y_include_doc/index.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>
Y_include_doc (test_package+re.Include2.Y_include_doc)
</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+re</a> » <a href="../index.html">Include2</a> » Y_include_doc
</nav>
<header class="odoc-preamble">
<h1>
Module <code><span>Include2.Y_include_doc</span></code>
</h1>
</header>
<div class="odoc-content">
<div class="odoc-include">
<div class="spec-doc">
<p>
Doc attached to <code>include Y</code>. <code>Y</code>'s top-comment shouldn't appear here.
</p>
</div>
<details open="open">
<summary class="spec include">
<code><span><span class="keyword">include</span> <span class="keyword">module</span> <span class="keyword">type</span> <span class="keyword">of</span> <span class="keyword">struct</span> <span class="keyword">include</span> <a href="../Y/index.html">Y</a> <span class="keyword">end</span><span class="keyword">;</span></span></code>
</summary>
<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><span> = <a href="../Y/index.html#type-t">Y.t</a></span><span>;</span></code>
</div>
</div>
</details>
</div>
</div>
</body>
</html>
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>
Y_include_synopsis (test_package+re.Include2.Y_include_synopsis)
</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+re</a> » <a href="../index.html">Include2</a> » Y_include_synopsis
</nav>
<header class="odoc-preamble">
<h1>
Module <code><span>Include2.Y_include_synopsis</span></code>
</h1>
<p>
The <code>include Y</code> below should have the synopsis from <code>Y</code>'s top-comment attached to it.
</p>
</header>
<div class="odoc-content">
<div class="odoc-include">
<details open="open">
<summary class="spec include">
<code><span><span class="keyword">include</span> <span class="keyword">module</span> <span class="keyword">type</span> <span class="keyword">of</span> <span class="keyword">struct</span> <span class="keyword">include</span> <a href="../Y/index.html">Y</a> <span class="keyword">end</span><span class="keyword">;</span></span></code>
</summary>
<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><span> = <a href="../Y/index.html#type-t">Y.t</a></span><span>;</span></code>
</div>
</div>
</details>
</div>
</div>
</body>
</html>
25 changes: 25 additions & 0 deletions test/html/expect/test_package+re/Include2/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,31 @@ <h1>
</div>
</details>
</div>
<div class="odoc-spec">
<div class="spec module" id="module-Y">
<a href="#module-Y" class="anchor"></a><code><span><span class="keyword">module</span> </span><span><a href="Y/index.html">Y</a></span><span>: { ... }</span><span>;</span></code>
</div>
<div class="spec-doc">
<p>
Top-comment of Y.
</p>
</div>
</div>
<div class="odoc-spec">
<div class="spec module" id="module-Y_include_synopsis">
<a href="#module-Y_include_synopsis" class="anchor"></a><code><span><span class="keyword">module</span> </span><span><a href="Y_include_synopsis/index.html">Y_include_synopsis</a></span><span>: { ... }</span><span>;</span></code>
</div>
<div class="spec-doc">
<p>
The <code>include Y</code> below should have the synopsis from <code>Y</code>'s top-comment attached to it.
</p>
</div>
</div>
<div class="odoc-spec">
<div class="spec module" id="module-Y_include_doc">
<a href="#module-Y_include_doc" class="anchor"></a><code><span><span class="keyword">module</span> </span><span><a href="Y_include_doc/index.html">Y_include_doc</a></span><span>: { ... }</span><span>;</span></code>
</div>
</div>
</div>
</body>
</html>
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ <h1>
<div class="odoc-include">
<div class="spec-doc">
<p>
Doc of <code>T</code>, part 2.
part 3
</p>
</div>
<div class="odoc-spec">
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,11 +24,6 @@ <h1>
</header>
<div class="odoc-content">
<div class="odoc-include">
<div class="spec-doc">
<p>
Doc of <code>T</code>, part 2.
</p>
</div>
<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><span>;</span></code>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ <h1>
<div class="odoc-include">
<div class="spec-doc">
<p>
Doc of <code>T</code>, part 2.
part 3
</p>
</div>
<div class="odoc-spec">
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,11 +24,6 @@ <h1>
</header>
<div class="odoc-content">
<div class="odoc-include">
<div class="spec-doc">
<p>
Doc of <code>T</code>, part 2.
</p>
</div>
<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><span>;</span></code>
Expand Down
2 changes: 1 addition & 1 deletion test/html/test.ml
Original file line number Diff line number Diff line change
Expand Up @@ -252,7 +252,7 @@ let source_files_all =
("module.mli", [ "Module/index.html" ]);
("interlude.mli", [ "Interlude/index.html" ]);
("include.mli", [ "Include/index.html" ]);
("include2.ml", [ "Include2/index.html" ]);
make_input "include2.ml" [ "Y_include_synopsis"; "Y_include_doc" ];
( "include_sections.mli",
[
"Include_sections/index.html";
Expand Down
11 changes: 11 additions & 0 deletions test/latex/expect/test_package+ml/Include2.tex
Original file line number Diff line number Diff line change
Expand Up @@ -6,5 +6,16 @@ \section{Module \ocamlinlinecode{Include2}}\label{container-page-test+u+package+
\ocamltag{keyword}{include} \ocamltag{keyword}{module} \ocamltag{keyword}{type} \ocamltag{keyword}{of} \ocamltag{keyword}{struct} \ocamltag{keyword}{include} \hyperref[container-page-test+u+package+++ml-module-Include2-module-X]{\ocamlinlinecode{X}} \ocamltag{keyword}{end}Comment about X that should not appear when including X below.

\label{container-page-test+u+package+++ml-module-Include2-type-t}\ocamlcodefragment{\ocamltag{keyword}{type} t = int}\\
\label{container-page-test+u+package+++ml-module-Include2-module-Y}\ocamlcodefragment{\ocamltag{keyword}{module} \hyperref[container-page-test+u+package+++ml-module-Include2-module-Y]{\ocamlinlinecode{Y}}}\ocamlcodefragment{ : \ocamltag{keyword}{sig}}\begin{ocamlindent}\label{container-page-test+u+package+++ml-module-Include2-module-Y-type-t}\ocamlcodefragment{\ocamltag{keyword}{type} t}\\
\end{ocamlindent}%
\ocamlcodefragment{\ocamltag{keyword}{end}}\begin{ocamlindent}Top-comment of Y.\end{ocamlindent}%
\medbreak
\label{container-page-test+u+package+++ml-module-Include2-module-Y+u+include+u+synopsis}\ocamlcodefragment{\ocamltag{keyword}{module} \hyperref[container-page-test+u+package+++ml-module-Include2-module-Y+u+include+u+synopsis]{\ocamlinlinecode{Y\_\allowbreak{}include\_\allowbreak{}synopsis}}}\ocamlcodefragment{ : \ocamltag{keyword}{sig}}\begin{ocamlindent}\ocamltag{keyword}{include} \ocamltag{keyword}{module} \ocamltag{keyword}{type} \ocamltag{keyword}{of} \ocamltag{keyword}{struct} \ocamltag{keyword}{include} \hyperref[container-page-test+u+package+++ml-module-Include2-module-Y]{\ocamlinlinecode{Y}} \ocamltag{keyword}{end}\label{container-page-test+u+package+++ml-module-Include2-module-Y+u+include+u+synopsis-type-t}\ocamlcodefragment{\ocamltag{keyword}{type} t = \hyperref[container-page-test+u+package+++ml-module-Include2-module-Y-type-t]{\ocamlinlinecode{Y.\allowbreak{}t}}}\\
\end{ocamlindent}%
\ocamlcodefragment{\ocamltag{keyword}{end}}\begin{ocamlindent}The \ocamlinlinecode{include Y} below should have the synopsis from \ocamlinlinecode{Y}'s top-comment attached to it.\end{ocamlindent}%
\medbreak
\label{container-page-test+u+package+++ml-module-Include2-module-Y+u+include+u+doc}\ocamlcodefragment{\ocamltag{keyword}{module} \hyperref[container-page-test+u+package+++ml-module-Include2-module-Y+u+include+u+doc]{\ocamlinlinecode{Y\_\allowbreak{}include\_\allowbreak{}doc}}}\ocamlcodefragment{ : \ocamltag{keyword}{sig}}\begin{ocamlindent}Doc attached to \ocamlinlinecode{include Y}. \ocamlinlinecode{Y}'s top-comment shouldn't appear here.\ocamltag{keyword}{include} \ocamltag{keyword}{module} \ocamltag{keyword}{type} \ocamltag{keyword}{of} \ocamltag{keyword}{struct} \ocamltag{keyword}{include} \hyperref[container-page-test+u+package+++ml-module-Include2-module-Y]{\ocamlinlinecode{Y}} \ocamltag{keyword}{end}\label{container-page-test+u+package+++ml-module-Include2-module-Y+u+include+u+doc-type-t}\ocamlcodefragment{\ocamltag{keyword}{type} t = \hyperref[container-page-test+u+package+++ml-module-Include2-module-Y-type-t]{\ocamlinlinecode{Y.\allowbreak{}t}}}\\
\end{ocamlindent}%
\ocamlcodefragment{\ocamltag{keyword}{end}}\\


Loading