JEP 413: Code Snippets in Java API Documentation

[Pavel Rappo]

Thanks for relaying that Twitter discussion. Although we've surveyed multiple systems before agreeing on the snippet markup syntax that satisfies the needs of our initial use case, OpenJDK, it is possible that we've missed some important features.

What are the important features of AsciiDoc's Tagged Regions that are impossible to achieve with the proposed JavaDoc snippet markup syntax?

I would encourage people to reply to this email thread. javadoc-dev at openjdk.java.net is one of the lower traffic OpenJDK mailing lists. One could subscribe to it for the duration of this discussion without concerns of getting too many unrelated notifications.

-Pavel

> On 30 Apr 2021, at 11:40, Gunnar Morling <gunnar at hibernate.org> wrote:
> 
> Hi all,
> 
> It's with great interest that I've learned about JEP 413, I think this will be a great improvement to the user experience of JavaDoc!
> 
> When sharing this online, there was feedback from several folks [1] that alignment for the region  selection syntax with that one of AsciiDoc would be desirable [2]. That way, one could easily include the same snippet into JavaDoc and other documentation like a developer guide at the same time. I believe that'd make lots of sense, so I thought I'd relay this feedback here.
> 
> Best,
> 
> --Gunnar
> 
> [1] https://twitter.com/maxandersen/status/1388018227868049408 <https://twitter.com/maxandersen/status/1388018227868049408>
> [2] https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions/ <https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions/>
>