Raw String Literals for JavaDoc

[Nir Lisker]

The compiled examples idea sounds appealing. Having recently gone over and
corrected many snippets for JavaFX controls I can see the usefulness of
having them be compile-able. My only worry is that it will require new
files just for a few lines of examples each. For example, we have a
'controls' package with classes for Label, Button, TextField etc. We
provide an example or two for each control, where would we put these 30
files? How do we not make them load with the classloader, which makes
startup time longer?


> If there is any discussion to be had at this point, I would say it is to
> understand the use cases.
>

 There are 2 use cases that immediately come to mind:
1. A single block as shown in [1].
2. A broken down block where each segment has a short discussion, as in [2]
under Creating a TableView.

- Nir

[1]
https://openjfx.io/javadoc/11/javafx.controls/javafx/scene/control/Accordion.html
[2]
https://openjfx.io/javadoc/11/javafx.controls/javafx/scene/control/TableView.html

On Sun, Jan 20, 2019 at 7:08 PM Jonathan Gibbons <
jonathan.gibbons at oracle.com> wrote:

> 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> 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/20190121/681a1aab/attachment-0001.html>