<div dir="ltr"><div class="gmail_quote"><div>Hello!</div><div><br></div><div>Thank you for the detailed answer, now things are much more clear.</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">> 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:<br>
> <br>
> class Test {<br>
> // @start region=r0<br>
> // @start region=r1<br>
> void one() {}<br>
> // @end<br>
> void two() {}<br>
> // @end<br>
> void three() {}<br>
> }<br>
> <br>
> I want to render the region r0. I write {@snippet file="Test.java" region=r0} and get in rendered HTML<br>
> void one() {}<br>
> void two() {}<br>
> 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:<br>
> <br>
> /**<br>
> * {@snippet file="Test.java" region=r0:<br>
> *<br>
> *<br>
> * void one() {}<br>
> *<br>
> * void two() {}<br>
> * }<br>
> */<br>
> <br>
> 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.<br>
<br>
Please file a bug for this.<br></blockquote><div><br></div><div>Filed: <a href="https://bugs.openjdk.org/browse/JDK-8305383">https://bugs.openjdk.org/browse/JDK-8305383</a></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">> 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...<br>
<br>
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.<br>
<br>
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 <a href="https://bugs.openjdk.org/browse/JDK-8304408?focusedCommentId=14570485&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-14570485" rel="noreferrer" target="_blank">https://bugs.openjdk.org/browse/JDK-8304408?focusedCommentId=14570485&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-14570485</a><br>
<br>
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.<br></blockquote><div><br></div><div>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.</div><div><br></div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">I've filed a bug on spec issues you've discovered: <a href="https://bugs.openjdk.org/browse/JDK-8305353" rel="noreferrer" target="_blank">https://bugs.openjdk.org/browse/JDK-8305353</a></blockquote><div><br></div><div>Thank you!</div><div><br></div><div>Tagir Valeev.</div></div></div>