[External] : Re: Snippet specification feedback

[Tagir Valeev]

Hello!

Thank you for the detailed answer, now things are much more clear.



> > In fact, the current implementation looks somewhat inconsistent, but
> it's unclear whether it's correct or not, as we have no specification. For
> example, consider the external snippet:
> >
> > class Test {
> > // @start region=r0
> > // @start region=r1
> > void one() {}
> > // @end
> > void two() {}
> > // @end
> > void three() {}
> > }
> >
> > I want to render the region r0. I write {@snippet file="Test.java"
> region=r0} and get in rendered HTML
> > void one() {}
> > void two() {}
> > No empty line between one and two. Ok, it was stripped. But if I use a
> hybrid snippet and want to remove markup from the inline version, the
> javadoc tool requires me to write this:
> >
> > /**
> > * {@snippet file="Test.java" region=r0:
> > *
> > *
> > * void one() {}
> > *
> > * void two() {}
> > * }
> > */
> >
> > So, in this case empty lines are not stripped (including even the line
> that starts the r0 region). Moreover, now the rendering is spoiled, as it's
> rendered with empty lines as well. It looks like, for rendering an inline
> version is preferred over the external version. This is not specified, and
> these versions may produce different result.
>
> Please file a bug for this.
>

Filed: https://bugs.openjdk.org/browse/JDK-8305383


> > There are more tricky questions like in which order several replacements
> or highlightings are applied, but probably it's ok to keep this part
> unspecified...
>
> Generally, snippet markup was supposed to be used for simple and
> straightforward cases. Complex markup, such as overlapping regions with
> replacements, quickly becomes hard to predict and diagnose. Additionally,
> we have not rigorously checked the markup model: is it sound or can it be
> contradictory in some cases? So there's also that.
>
> It's good that you are looking into this, because it pushes us to improve
> the spec. That said, even javadoc is qui We might want an API, such as the
> one described in this comment
> https://bugs.openjdk.org/browse/JDK-8304408?focusedCommentId=14570485&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-14570485
>
> It would be good if IDEs, REPLs or editors didn't have to maintain their
> own implementations of the spec and instead focused on a much easier task:
> having an up-to-date version of a library that provides jdk.javadoc
> services, such as (i) "render documentation for this symbol" or (ii)
> "lint/parse this doc comment". Think Language Server Protocol, but simpler
> and specifically for javadoc. I know that such a library will not eliminate
> the need for good spec (if nothing else, authors need spec to build their
> mental model of what's going on), but at least it will provide a great deal
> of uniformity and reduce maintenance effort.
>

That would be great, though probably not completely useful for us. E.g., we
have our own incremental parser and own parse tree model which includes
both javadoc and the surrounding java code in a single tree. It might be
non-trivial to incorporate a foreign parser for some subtrees there. Also,
there will be a transition period, as IDE boot JDK may be older than
project JDK. E.g., now IntelliJ IDEA works on JDK 17 but it supports all
the syntax features up to JDK 20. Nevertheless, parts of the API might be
perfectly reusable. Feel free to ping me to review such an API if you come
up with it.


I've filed a bug on spec issues you've discovered:
> https://bugs.openjdk.org/browse/JDK-8305353


Thank you!

Tagir Valeev.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/javadoc-dev/attachments/20230331/34742c92/attachment-0001.htm>