javadoc 的 markdown 替代品，也适用于 IDE

Question

我已经找到了一个可能的解决方案，描述于https://dzone.com/articles/using-markdown-syntax-javadoc，它基于https://github.com/Abnaxos/pegdown-doclet。 这使得 Markdown 支持能够替代在 Javadoc 中编写丑陋的 HTML 标签。

在 GitHub 页面上，还有一个“markdown-company-tooltip”解决方案作为在 IntelliJ 中使用 CTRL+Q 工具提示的插件，效果好 50%。

举个例子，Javadoc 目前的样子：

/**
 * 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 {
...
}

所以，如果您在 IDE 中的类上进行工具提示/鼠标悬停，那就没问题了。 然而，如果您直接位于相关类中，则由于 HTML 标记和其他宏的原因，很难阅读。这只是一个非常简单的示例，没有任何 Javadoc 特定宏。

所以，正如上面网站所描述的，我想直接将源代码中的Javadoc内容替换为Markdown语法。应用到这个例子，这看起来像：

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

将鼠标悬停在 Eclipse 中的

PersonTypes

枚举上时，Markdown 语法会丢失，因为 Eclipse 默认将其解释为 Javadoc 而不是 Markdown。

不幸的是，我目前没有找到为 Eclipse 启用 Markdown 工具提示解析的解决方案。 还有其他人有解决方案或其他想法吗？

Answer 1

IntelliJ 有一个插件支持 markdow javadoc https://plugins.jetbrains.com/plugin/9840-markdown-doclet-for-idea

注意该插件自2017年以来就没有更新过 并且maven插件自2016年以来就没有更新过，参见https://mvnrepository.com/artifact/ch.raffael.pegdown-doclet/pegdown-doclet

Answer 2

在 Java 13 中，删除了旧版 doclet API (

com.sun.javadoc

)，只能使用 Java 9 中引入的新 doclet API (

jdk.javadoc.doclet

)。

jdrupes-mdoclet 是

abnaxos/pegdown-doclet

的替代方案，支持新的 doclet API 和现代 JVM（版本 3 为 Java 17）。

另请注意，存在一个 JEP 草案，用于将此功能添加到标准

javadoc

工具中。然而，这个 JEP 目前已撤回，“等待额外的设计讨论”。

更新：要使用

jdrupes-mdoclet

与 Maven，请参阅 https://github.com/mnlipp/jdrupes-mdoclet/issues/11

Answer 3

从 Java 23 开始，JavaDoc 支持 Markdown。 请参阅 JEP 467 了解语法。