JEP 467: Enhanced Markdown Comments

[mechite]

Discussion about support for this ongoing in the Discord thread:
JEP 467: Enhanced Markdown Comments

avaje-http reads Javadoc for OpenAPI generation.

• If we modify the test suite to have a markdown version, Avaje build toolchain requires Java 25+ then
• If we bump that requirement, doesn't it also make sense for Avaje to start using that kind of doc internally too?
  • I do not mind personally doing the boring refactoring to make all our Javadoc use the new format
  • It is possible to use Markdown comments on an older Java release.
    • You can even target Java 11 and use JDK 25 as your build toolchain, and use markdown comments.
    • The only things this affects is - 1) cannot build Javadoc site without JDK 25 - 2) some people may have outdated IDEs?

Modifying the generator to support both Javadoc syntax should not be too difficult.

• We are only reading main Javadoc description - but I don't think the current solution supports e.g. {@link }?
• We only read that up-to the last period (.)?
• Stuff like @return, @param is unchanged. We just need to be able to support both /// & /**.

^{that something is not complex doesn't mean it can't be a lot of work :-)}

[SentryMan]

add JEP 367 support

ok but does it not work now? That is, even now we don't have to parse out the /** or the various *, because the apt api we use to get the comments just spits the text content of the comments

[mechite]

does it not work now?

Nope, so I think that should be an issue for that library then

Once it works, the test in that PR should pass, and I guess there is no other changes to make?
^{Even if the type of markdown comment is an implementation detail of some library, I think it still improves our test coverage to directly test this case?}

So it could just be merged afterwards

[SentryMan]

no like, I'm testing it and it works

[SentryMan]

Nope, so I think that should be an issue for that library then

we pull it from the JDK, not a library

[SentryMan]

Closing as we already support