On 1/26/21 7:47 AM, Roger Riggs wrote:
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?
We'll need to address that. Ideas are to either allow an addition
`module=` or use the `module/package.Class` convention.
* Does the "lang=" tag need to be a closed set; if it were open, it
would give more flexibility in the checking tools
It should be open.
* 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.
Yes. The current plan is to leverage ideas from text blocks, like
`stripIndent`
*
* Can the markup tags be nested, for example a region within a region?
(@start: A...@start: B...@end: B...@end: A)
Current idea is no restrictions, so they can nest or overlap.
*
* Markup: Can "text" include html or other javadoc markup, otherwise
an error?
I'm not sure the exact context you mean for "text". You may mean the
`@insert` markup tag.
If so, the current answer is "don't know", but "yes" would be nice.
* 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>;"'
yes, `@replace` is needed to display "invalid" text when you also expect
other analysis to
be done on the underlying text. For example, if you want to be able to
validate the source code as
compilable, or if you want more than just regex highlighting, then the
underlying text
has to be "valid". If you're OK for the text to just be a blob of
plain text, then `@replace`
is obviously not required.
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
