Generate markdown-formatted javadoc

jwharm commented

2024-08-31 17:37:16 +02:00

(Migrated from github.com)

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.

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 commented

2025-07-05 15:02:43 +02:00

(Migrated from github.com)

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 commented

2025-07-05 15:25:21 +02:00

(Migrated from github.com)

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.

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.

👍 1

jwharm commented

2026-03-19 15:13:42 +01:00

Owner

Fixed with !335

jwharm closed this issue

2026-03-19 15:13:42 +01:00

Rows
Columns

Generate markdown-formatted javadoc #134