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.gibb...@oracle.com <mailto:jonathan.gibb...@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
