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