Question

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

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

但是在生成的javadoc中，这看起来相当单调乏味，我更倾向于使用类似于SyntaxHighlighter的语法突出显示。

如何做到这一点？

Answer 1

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

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

并且PRE标记内的所有文本都将突出显示为java。查看上面的链接以获取更多信息。

Answer 2

另一种选择是使用pegdown-doclet，它允许你使用Github风格的围栏代码块。

```java
public static class Example {}
```

Answer 3

这里的其他答案都可以，但是会引入其他依赖性或增加构建复杂性。如果您使用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，所以如果有人想加入并添加它，请这样做。

Answer 4

迟到总比没有好。

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

答案假定您正在使用Maven，但它的好处是所有您的项目将自动继承在Javadoc中进行语法突出显示的功能。您不必须为每个项目执行此操作。使用此配方，您无需在每个项目中执行任何操作即可获得该功能。

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

Answer 5

发现此问题正在寻找其他内容。在过渡期间，我编写了一个工具，将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

javadoc的语法高亮？

5 个答案: