Raw String Literals for JavaDoc

[Nir Lisker]

The separate source tree does solve my concerns.

 would you want to also publish the entire source code for the files
> containing the snippets
>

Iv'e given it some thought. I don't think it's necessary to publish the
whole source, but it could be useful on occasions. So it comes down to the
usual dilemma of effort vs. benefit. For my work on JavaFX, a full source
file would include the ceremonies around showing how to use the class
(setting up a Stage and a Scene) and the snippet is just the few lines as
shown above. On the other hand, JavaFX has tutorials that already have full
code examples [1], so I'm doubtful the user would *need* the snippet's
source.

 ... and would that affect how you would want to identify the snippets
> within the source files?
>

I don't think so. If I have a full source and I mark the snippet lines in
some way, publishing the full source or not makes no difference, except
that maybe the annotation/tag for marking the snippet should not be
displayed so that copy-paste is easier.

- Nir

[1]
https://docs.oracle.com/javase/8/javafx/user-interface-tutorial/accordion-titledpane.htm

On Mon, Jan 21, 2019 at 6:07 PM Jonathan Gibbons <
jonathan.gibbons at oracle.com> wrote:

> Nir,
>
> "where would we put these 30 files?" ... given that one of the goals would
> be to make it easy to compile the files, the files should probably be in
> their own source tree, whose root is identified to the standard doclet with
> a new "path" option, such as `--snippet-path`. Within that source tree, it
> would be up to the author to organize the files in whatever manner is
> convenient. You could either have one big source file with lots of snippets
> within it, or could organize the files in a traditional package hierarchy.
> I'm not sure I understand the comment about the classloader ... as far as
> javadoc is concerned, they would just be source files, containing
> somehow-identifiable snippets; as far as making the files executable, that
> would be up to the author to make happen as they wish -- issues with
> startup time would not be relevant to javadoc itself.  Note that by
> suggesting that the source files should be in their own source tree, it
> would be up to the author to provide any additional infrastructure to
> compile/test/run the examples, using the infrastructure of their choice
> (i.e. Makefile/Ant/Maven/Graal/etc)
>
> I agree with your use cases, but the question common to both uses is,
> would you want to also publish the entire source code for the files
> containing the snippets ... and would that affect how you would want to
> identify the snippets within the source files?
>
> -- Jon
> On 1/20/19 5:06 PM, Nir Lisker wrote:
>
> 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/20190124/a39ff7a6/attachment.html>