javadoc的语法高亮显示？

Posted 2023-03-05

【中文标题】javadoc的语法高亮显示？

【英文标题】：syntax highlighting for javadoc?

【发布时间】：2010-11-26 08:53:59

【问题描述】：

目前我在我的 javadoc 中使用 PRE 标记格式化代码示例，例如：

/**
 * Example javadoc
 * 
<pre>
String foo = "bar";
</pre>
 *
 * @return   true if the operation completed
 */

但这在生成的 javadoc 中显得相当单调乏味，我更希望有一些类似于 SyntaxHighlighter 的语法突出显示。

如何做到这一点？

【参考方案1】：

这里的其他答案都有效，但会引入额外的依赖项或增加额外的构建复杂性。如果您使用 Maven 生成文档，并希望以最简单的方式使其在没有额外文件或依赖项的情况下工作，请添加到 maven-javadoc-plugin 配置：

<additionalOptions>-html5 --allow-script-in-comments</additionalOptions>
<header><![CDATA[
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.13.1/styles/vs.min.css">
    <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.13.1/highlight.min.js"></script>
    <script type="text/javascript">hljs.initHighlightingOnLoad();</script>
]]></header>

完整的插件配置如下所示：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.0.1</version>
    <configuration>
        <additionalOptions>-html5 --allow-script-in-comments</additionalOptions>
        <nohelp>true</nohelp>
        <show>private</show>
        <header><![CDATA[
            <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.13.1/styles/vs.min.css">
            <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.13.1/highlight.min.js"></script>
            <script type="text/javascript">hljs.initHighlightingOnLoad();</script>
        ]]></header>
    </configuration>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Pick your theme from here 并将上面的“vs”替换为您喜欢的主题（所有小写字母，单词之间带有破折号，例如mono-blue；如果您想要的主题不起作用，您可以查看here获取可用文件列表）。

然后像这样写你的例子：

 /**
  * Does something cool.
  * <pre><code class="java">@code
      // some example code here
      int x = 5;
  * </code></pre>
  */

https://burningmime.gitlab.io/setmatch/javadoc/com/burningmime/setmatch/RuleDB.html

编辑：您实际上并不需要 <pre><code class="java"> 中的课程。您可以修改该 javascript 位，以便根本不需要更改源文件，并且 @code 部分中的任何内容都将突出显示，因为 Javadoc 已经添加了 <code> 标记。我不知道足够多的 JavaScript 来做到这一点，但应该不会太难。该解决方案可能是所有解决方案中侵入性最小的，因为它只是构建配置中的几行代码。

我正在标记这个社区 wiki，所以如果有人想加入并添加它，请这样做。

【参考方案2】：

另一种选择是使用pegdown-doclet，它允许您使用 Github 风格的防护代码块。

```java
public static class Example 
```

【参考方案3】：

发现这个问题正在寻找其他东西。在此期间，我编写了一个工具，将 gist 示例嵌入到 JavaDoc 中：https://www.codenameone.com/blog/javadoc-source-samples-that-dont-suck.html

您可以在我们的代码中看到这一点，例如： https://www.codenameone.com/javadoc/com/codename1/components/MediaPlayer.html

https://www.codenameone.com/javadoc/com/codename1/ui/package-summary.html

【参考方案4】：

迟到总比没有好。

我的这个answer 解释了——尽管它的标题——如何使用 SyntaxHighlighter 作为 OP 请求向您的 Javadocs 添加语法突出显示功能。

答案假设您使用的是Maven，但它的好处是所有您的项目将自动继承在Javadoc 中进行语法高亮显示的能力。您将不必为每个项目都这样做。有了这个秘籍，您无需在每个项目中执行任何操作即可拥有该功能。

此外，如果您想要进行样式自定义（即您的 Javadoc 的外观），这与您将使用的机制相同。

【参考方案5】：

您可以使用jQuery 使用beautyOfCode 插件来完成它。我不确定是否有一种简单的方法可以连接到 javadoc 生成，但事后您可以在标题中执行以下操作：

$(function()  
    $("pre").beautifyCode('java');  
);

PRE 标记中的所有文本都将突出显示为 java.lang.查看上面的链接了解更多信息。