<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body>
<p><br>
</p>
<div class="moz-cite-prefix">On 1/26/21 7:47 AM, Roger Riggs wrote:<br>
</div>
<blockquote type="cite" cite="mid:a10c8887-559a-0d73-b76f-c42206e90d4d@oracle.com">
Hi,<br>
<br>
A very useful proposal.<br>
<br>
A few comments, I expect these will be addressed as the
development proceeds.<br>
<ul>
<li>In the @snippet tag, can the "class=" indicate a module name
in addition to the class name?</li>
</ul>
</blockquote>
<p>We'll need to address that. Ideas are to either allow an addition
`module=` or use the `module/package.Class` convention.<br>
</p>
<p><br>
</p>
<blockquote type="cite" cite="mid:a10c8887-559a-0d73-b76f-c42206e90d4d@oracle.com">
<ul>
<li>Does the "lang=" tag need to be a closed set; if it were
open, it would give more flexibility in the checking tools</li>
</ul>
</blockquote>
<p>It should be open.</p>
<p><br>
</p>
<blockquote type="cite" cite="mid:a10c8887-559a-0d73-b76f-c42206e90d4d@oracle.com">
<ul>
<li>Indentation: The handling of whitespace may need a bit more
care. Is the snippet text treated as a single string so
whitespace is stripped only from the first line, or every line
individually.<br>
Perhaps some of the logic from text-blocks can be used to keep
the lines aligned even while discarding common leading
whitespace. For example, supposing an external file with
nested classes and fairly deep indentation in the snippet to
be shown.<br>
</li>
</ul>
</blockquote>
Yes. The current plan is to leverage ideas from text blocks, like
`stripIndent`<br>
<blockquote type="cite" cite="mid:a10c8887-559a-0d73-b76f-c42206e90d4d@oracle.com">
<ul>
<li> <br>
</li>
<li>Can the markup tags be nested, for example a region within a
region? <br>
(@start: A...@start: B...@end: B...@end: A)<br>
</li>
</ul>
</blockquote>
<p>Current idea is no restrictions, so they can nest or overlap.</p>
<p><br>
</p>
<blockquote type="cite" cite="mid:a10c8887-559a-0d73-b76f-c42206e90d4d@oracle.com">
<ul>
<li> <br>
</li>
<li>Markup: Can "text" include html or other javadoc markup,
otherwise an error?</li>
</ul>
</blockquote>
I'm not sure the exact context you mean for "text". You may mean
the `@insert` markup tag.<br>
<p>If so, the current answer is "don't know", but "yes" would be
nice.</p>
<p><br>
</p>
<blockquote type="cite" cite="mid:a10c8887-559a-0d73-b76f-c42206e90d4d@oracle.com">
<ul>
<li>Is "@replace" needed to show text that would otherwise be
invalid for the language?<br>
For example, '@replace "var a = null;" "var a = <your data
here>;"'</li>
</ul>
</blockquote>
yes, `@replace` is needed to display "invalid" text when you also
expect other analysis to<br>
be done on the underlying text. For example, if you want to be able
to validate the source code as<br>
compilable, or if you want more than just regex highlighting, then
the underlying text<br>
has to be "valid". If you're OK for the text to just be a blob of
plain text, then `@replace`<br>
is obviously not required.
<p><br>
</p>
<blockquote type="cite" cite="mid:a10c8887-559a-0d73-b76f-c42206e90d4d@oracle.com">
<ul>
</ul>
Thanks, Roger<br>
<br>
<br>
<div class="moz-cite-prefix">On 1/22/21 7:50 PM, Jonathan Gibbons
wrote:<br>
</div>
<blockquote type="cite" cite="mid:3d4aec85-776d-aa4f-49ad-36015ed0d88d@oracle.com">FYI,
<br>
<br>
JDK-8201533: Enhanced javadoc support for code samples
(snippets) <br>
<br>
This is a draft JEP that describes a proposal for a new doc
comment tag to replace the use of `<pre>{@code
...}</pre>` to include code samples (also known as
"snippets") in API documentation comments. <br>
<br>
Feedback, comments welcome. <br>
<br>
-- Jon, on behalf of the JavaDoc team <br>
<br>
<a class="moz-txt-link-freetext" href="https://bugs.openjdk.java.net/browse/JDK-8201533" moz-do-not-send="true">https://bugs.openjdk.java.net/browse/JDK-8201533</a>
<br>
<br>
<br>
</blockquote>
<br>
</blockquote>
</body>
</html>