Hi,
A very useful proposal.
A few comments, I expect these will be addressed as the development
proceeds.
* In the @snippet tag, can the "class=" indicate a module name in
addition to the class name?
* Does the "lang=" tag need to be a closed set; if it were open, it
would give more flexibility in the checking tools
* 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.
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.
* Can the markup tags be nested, for example a region within a region?
(@start: A...@start: B...@end: B...@end: A)
* Markup: Can "text" include html or other javadoc markup, otherwise
an error?
* Is "@replace" needed to show text that would otherwise be invalid
for the language?
For example, '@replace "var a = null;" "var a = <your data here>;"'
Thanks, Roger
On 1/22/21 7:50 PM, Jonathan Gibbons wrote:
FYI,
JDK-8201533: Enhanced javadoc support for code samples (snippets)
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.
Feedback, comments welcome.
-- Jon, on behalf of the JavaDoc team
https://bugs.openjdk.java.net/browse/JDK-8201533
