Draft JEP for upcoming work on snippets

[Jonathan Gibbons]

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... at start: B... at end: B... at 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
>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20210126/22fd6df4/attachment-0001.htm>