Generate markdown-formatted javadoc

[jwharm]

Gtk API documentation (gi-docgen) is in markdown format. To generate clean-looking Javadoc, java-gi runs a series of regular expressions to translate markdown formatting to HTML. This works well enough in many cases, but some formatting, like tables, are not translated.

With JEP 467, OpenJDK 23 introduces markdown-formatted Javadoc. This would be a natural fit for java-gi. However, there are two disadvantages:

• JavaPoet doesn't support newer JDK features, and has been in maintenance mode with no new releases planned. So it will probably need to be forked to generate the new Javadoc syntax.
• This will raise the minimum required Java version to OpenJDK 23. All users will have to upgrade.

[MMarco94]

I don't think JDK 23 vs 22 is a significant issue for most users: the support window for non LTS releases of the JDK is relatively small, and JDK22 is already out of support, see https://www.oracle.com/java/technologies/java-se-support-roadmap.html

[jwharm]

You're right, nobody should be on JDK 22 anymore. The lack of markdown support in Javapoet is the blocking issue for this.

To be honest, the current markdown to javadoc conversion is good enough that this isn't a priority for me.