Draft JEP for upcoming work on snippets

[Dmitry Timofeev]

Hi everyone,

Happy to see a JEP improving support for code snippets! I’ve got some
feedback from the user perspective, and from some prototyping to support
Javadoc snippet compilation:

> hide = regex —

Would it be possible to have a simpler mechanism? For example, Rust code
snippets use # at the beginning of the line to hide it [1]. From the user
perspective, it is very easy to use and maintain — you don’t have to design
a regex, you won’t get any surprises from its evaluation, or read/maintain
some over-complicated pattern that slipped through code review.

[1]:
https://doc.rust-lang.org/rustdoc/documentation-tests.html#hiding-portions-of-the-example

> lang=name — […] Valid names are java, properties and text

Would it be possible to specify any language, as the goal seems to be to
pass this information to any rendering tools? Some converter libraries
might use snippets with configs (xml, json, …), some FFI libs — in
C++/Rust, some libs might provide examples for some JVM-based languages.

> region=name —

Would it make sense to provide some kind of selectors for Java constructs?
E.g., block:<method_name, or class_name> selecting the corresponding method
or class? This plugin for Mkdocs does that, but it operates on text, not on
AST, therefore, some unexpected curly braces break it (e.g., in string
literals) [2]. However, even simple text-based selection works well. Does
the Javadoc have the luxury of having ready access to the AST? Or is it too
complex to implement/maintain?

[2]: https://github.com/rnorth/mkdocs-codeinclude-plugin#usage

> For inline snippets, especially those that are not a full compilation
unit, it will be up to the test infrastructure to "wrap" the code fragment
in a full compilation unit, such that it can be compiled and possibly
executed.

Would it be possible to keep the non-goal of not providing a standard tool
to test them (to limit the scope of the JEP), but suggest a
format/restrictions/expansion procedure on the snippets to support such
test infra well (or enable adding it to JDK in the future)? I agree that
external snippets work well (especially for large-ish fragments), but for
some small things it is an overkill (you have to somehow configure the
build system to build these files, but exclude from the final artifact,
etc.), yet as a user I’d love to check their correctness. Would it make
sense to:
- Specify a standard way how a snippet is expanded (e.g., wrapped inside
Callable#call, or some standard template — Java language designers are in a
perfect position to pick a great one). [3]
- Specify a set of tags that define the expectations of the expanded
snippet behaviour (not sure it can be pulled into the scope, but the tools
will require that information): [4]
    - Compiles/fails compilation
    - Runs successfully/Throws exception
    - Is totally ignored.

In Rust doctests, for example, all these things are supported:
[3]
https://doc.rust-lang.org/rustdoc/documentation-tests.html#pre-processing-examples
(adds main unless you do that)
[4] https://doc.rust-lang.org/rustdoc/documentation-tests.html#attributes

Finally, you might be interested in the previous attempts to implement such
a tool for Java: https://github.com/jakewins/javadoctest
Beware the docs aren’t updated, its current version does not require
writing test manually, and finds and extracts snippets on itself, e.g.:
https://github.com/jakewins/javadoctest/blob/master/junit-platform-engine/src/test/java/javadoctest/engine/fixture/FixtureDocTestSimple.java#L18-L22

-- 
Best regards,
Dmitry Timofeev
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20210129/05a2dc4a/attachment.htm>