JEP 413 Questions

[Pavel Rappo]

> On 18 Oct 2021, at 16:32, Gunnar Morling <gunnar at hibernate.org> wrote:
> 
> <snip>
> 
> I've had a few questions about things which were not quite clear to me from the JEP:
> 
> * When not explicitly specifying the snippet path, where will JavaDoc look for the default exactly? Say I'm following the standard Maven project structure with a source dir under src/main/java, where would the snippet directory be expected by default? I've tried different places, but always ran into "snippet-files" being treated as a (non-valid) package name

The "snippet-files" directory is expected to be rooted at the package that refers to an external snippet. If a build tool or an IDE considers "snippet-files" as a package itself, then it might be problematic. 

> * (How) can I have end-of-line comments which should be propagated to rendered docs (e.g. explaining the code on that line) but also contain some tag?

In an end-of-line comment, only the rightmost suffix that can be parsed as this, will be recognized as markup:

    // @tag1 tag1-attributes @tag2 tag2-attributes ...

If there's no such suffix, then the line contains no markup. Note that you can always add a no-op suffix if you want your comment to not be interpreted as markup. 

> * When including an external snippet, I got a superfluous empty line at the beginning of the snippet (see last example in the blog post); is there any way to avoid that?

To avoid that, place @start at the end of the first line you want to include. In your post example, this translates to:

  ACMEConfiguration configuration = Validation // @start region="provider"

> 
> Thanks again,
> 
> --Gunnar
> 
> [1] https://www.morling.dev/blog/executable-javadoc-code-snippets/
>