Raw String Literals for JavaDoc

Mon Jan 21 16:07:51 UTC 2019

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 <mailto: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
>>     <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/20190121/da3d1f66/attachment.html>