> On 18 Oct 2021, at 16:32, Gunnar Morling <[email protected]> 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/
>
