Draft JEP for upcoming work on snippets

[Roger Riggs]

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... at start: B... at end: B... at 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
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20210126/bbd7167c/attachment.htm>