markdown replacement for javadoc, also for IDEs

Question

I found already a possible solution, described at https://dzone.com/articles/using-markdown-syntax-javadoc, which is based upon https://github.com/Abnaxos/pegdown-doclet. This enables markdown support as a replacement for writing the ugly HTML tags in Javadoc.

On the GitHub page, there is also a "markdown-compatible-tooltip" solution as plugin for using the CTRL+Q tooltip in IntelliJ, which is 50% good.

Just to give an example, how the Javadoc is currently looking:

/**
 * This enum gives you insight for various person characteristics.
 * <p>
 * This could be the following:
 * <ul>
 * <li>introvert</li>
 * <li>extrovert</li>
 * </ul>
 */
public enum PersonTypes {
...
}

So, it's ok, if you tooltipping/mouse-hovering over the class in an IDE. Nevertheless, it's hard to read if you are directly in the concerned class, caused by the HTML tags and other macros. And this is only a very simple example without any Javadoc specific macros.

So, as described on the website above, I'd like to replace the Javadoc stuff with the Markdown syntax in the source code directly. Applied to the example, this would look like:

/**
 * This enum gives you insight for various person characteristics.
 * 
 * This could be the following:
 *
 * - introvert
 * - extrovert
 * 
 */
public enum PersonTypes {
...
}

When hovering over PersonTypes enum in Eclipse, the Markdown syntax is getting lost, because Eclipse interprets it as Javadoc and not as Markdown by default.

Unfortunately I currently have no solution found for enable that Markdown tooltip parsing for Eclipse. Does anyone else have a solution or other ideas?

Answer 1

IntelliJ has a plugin to support markdow javadoc https://plugins.jetbrains.com/plugin/9840-markdown-doclet-for-idea

Note that the plugin has not been updated since 2017 and the maven plugin has not been updated since 2016, see https://mvnrepository.com/artifact/ch.raffael.pegdown-doclet/pegdown-doclet