-
Notifications
You must be signed in to change notification settings - Fork 100
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
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
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> |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. 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 ? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
I don't understand the question. Also:
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.
That would be my understanding as well. But:
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) There was a problem hiding this comment. Choose a reason for hiding this commentThe 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
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
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> | ||
|
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> |
There was a problem hiding this comment.
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 ?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No, it's removed.