Draft JEP for upcoming work on snippets

Tue Jan 26 17:40:54 UTC 2021

Roger,

I'd add to what Jon has already said about indentation. Early on in our prototype we recognized the need for clear rules and convenient control for indentation. We knew that having those would allow "Snippets" to improve on the solution provided by the "pre-code" compound:

    <pre>{@code <line 0>
        <line 1>
        <line 2>
        ...
        <line n>
    }</pre>

We realized that the problem of indentation and whitespace in multiline blocks was not by any means new and had been successfully solved in Text Blocks (JEPs: 355, 368, 378); and to some extent we reused that solution in the current prototype of "Snippets". Currently the prototype utilizes text-blocks-like solution in two constructs: (i) the {@snippet} tag and (ii) the region marked by `@start/@end`. If we depict this using the notation of JEP 378, we will get this:

i.

    {@snippet name1=value1 name2=value2
                   name3=value3 :
........      <html>
........          <body>
........              <p>Hello, world</p>
........          </body>
........      </html>
........}

ii.

    // @start name
........      <html>
........          <body>
........              <p>Hello, world</p>
........          </body>
........      </html>
........// @end name

The current prototype distinguishes between incidental and essential whitespace using the following pairs of tokens: (i) `:` and `}`, and (ii) `@start name` and `@end name`; this is similar to Text Blocks. That said, the prototype does NOT recognize escape sequences that Text Blocks recognize.

I'd stress that this is not set in stone and that the design space for indentation in snippets has not been fully explored. We are still exploring it and will update the JEP draft accordingly.

-Pavel

> On 26 Jan 2021, at 16:06, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> 
> 
> 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 
>>> 
>>> 
>> 