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

Reply via email to