Raw String Literals for JavaDoc

[Jonathan Gibbons]

Nir,

We're not there yet; we're just at the brainstorming stage. There is 
nothing public at this point.

Here are some of the high-level points.

1. As far as JLS/javac is concerned, there is nothing special about 
documentation comments: they are just instances of "/*...*/" comments, 
which means that we will never be able to support literal unescaped use 
of "*/" within a comment.

2. For the standard doclet, there is a syntactic assumption about `@` at 
the beginning of a line, which is used to split the doc comment into an 
initial run of text, followed by the block tags. This is what causes 
problems for annotations in code samples. While we could modify that 
rule, it would mean we would have to do more detailed parsing of every 
comment, to determine the initial text and block tags.

3. While it is convenient to have "inline snippets" in doc comments, it 
is worth noting that there have been instances where snippets have been 
incorrect or invalid. Thus, there is an interest to support out-of-line 
snippets, taken from external source files, that can separately be 
compiled and/or tested.  This suggests a tag like `{@example /args/}` or 
`{@snippet /args/}`.

4. For a tag like `{@snippet /args/}`, the discussion becomes, "what are 
the args". Two suggestions are: the name of a method whose body to 
include, or a range of text between markers, given in comments.  Either 
could work, but then the discussion turns to the use cases. Is this just 
about snippets to include in the doc comment? Some have suggested that 
it would be worth being able to link to a copy of the complete source 
file in the generated documentation, for a big picture example of how to 
use an API.  If the entire source is to be copied to somewhere in the 
documentation, then the issue of what delimiters to use for the inline 
snippet becomes more significant: do you want to see the markers, do you 
want to have to structure the source to arrange for suitable method 
boundaries, etc.

5. Some have suggested migrating towards the use of Markdown to replace 
the use of HTML in doc comments.  While Markdown would give us a 
new/different way to solve the `<pre>{@code...` problem, it would not 
solve the issues outlined in any of the preceding discussion.

If there is any discussion to be had at this point, I would say it is to 
understand the use cases. Is this about being able to include multiple 
small mostly-unrelated snippets of code, such as a few lines of code to 
give examples of how to use methods in an API, without necessarily being 
able to also include the entire source file somewhere, or is this about 
being able to write a high level narrative description, with selected 
snippets, of a complete working example program?

-- Jon

On 1/19/19 7:38 PM, Nir Lisker wrote:
> Hi Jon,
>
> Is any relevant material (discussion/prototype etc.) available to the 
> public or are you not there yet?
>
> - Nir
>
> On Sat, Jan 19, 2019 at 12:37 AM Jonathan Gibbons 
> <jonathan.gibbons at oracle.com <mailto:jonathan.gibbons at oracle.com>> wrote:
>
>     Nir,
>
>     There are some fundamental reasons why it is not possible to all
>     of what
>     you suggest in the way you suggest (i.e. using raw string
>     literals) For
>     the most obvious example, albeit a bit of an obscure case, would be a
>     raw string literal containing a /*...*/ comment. Similar problems
>     apply
>     to the appearance of `@` which already has an existing meaning in
>     documentation comments.
>
>     That being said, we are already investigating better ways to include
>     code samples and snippets in documentation comments, perhaps by being
>     able to insert code from a "nearby" source file, which would have the
>     advantage that (separately) the source file could itself be
>     compiled to
>     ensure that it is syntactically correct.
>
>     -- Jon
>
>
>     On 01/18/2019 02:08 PM, Nir Lisker wrote:
>     > Hi,
>     >
>     > I sent am email to amber-dev about the possibility of using Raw
>     String
>     > Literals in JavaDoc [1]. I was sent here and told there was some
>     > discussion in this area. Would what I describe in [1] be
>     possible in
>     > some form?
>     >
>     > Thanks,
>     > Nir
>     >
>     > [1]
>     >
>     https://mail.openjdk.java.net/pipermail/amber-dev/2019-January/003906.html
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190120/0b990fda/attachment.html>