syntax highlighting for javadoc?

问题

Currently I format code examples in my javadoc using the PRE tag e.g.:

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

But this turns out rather monotone and boring in the resulting javadoc, I'd much rather have some syntax highlighting similar to SyntaxHighlighter.

How can this be done?

回答1:

You can use jQuery to get it done using the beautyOfCode plugin. I'm not sure if there's an easy way to hook into the javadoc generation, but after-the-fact you can just do the following in your header:

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

and all text inside PRE tags will be highlighted as java. Check out the links above for more info.

回答2:

Another option is to use pegdown-doclet, which lets you use Github-style fenced code blocks.

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

回答3:

The other answers here all work, but introduce additional dependencies or add additional build complexity. If you're using Maven to generate the docs, and want the simplest way to get this to work with no extra files or dependencies, then add to the maven-javadoc-plugin config:

<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>

The full plugin configuration will look something like this:

<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 and replace the "vs" above with the theme you like (all lower case w/ dashes between words, so like mono-blue; if the one you want isn't working, you can look here for a list of available files).

Then write your examples like this:

 /**
  * 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

EDIT: You don't actually need the class in <pre><code class="java">. You can modify that javascript bit so that you don't need to change the source files at all, and anything in the {@code} parts will get highlighted, since Javadoc already adds the <code> tag. I don't know enough JavaScript to do that, but it shouldn't be too hard. That solution is probably the least invasive of all, since it would just be a couple lines in the build config.

I'm marking this community wiki, so if someone wants to come along and add that, please do so.

回答4:

Better late than never.

This answer by me explains - despite its title - how to add syntax highlighting feature to your Javadocs using SyntaxHighlighter as the OP requests.

The answer assumes you're using Maven but it has the benefit that all your projects will automatically inherit the ability to do syntax highlighting in Javadoc. You'll not have to do this for each and every project. With this recipe there's nothing you need to do in each project to have the feature.

Additionally this is the same mechanism you would use if you wanted to do style customizations (i.e. how your Javadoc looks).

回答5:

Found this question looking for something else. In the interim I wrote a tool that embeds gist samples into JavaDoc in: https://www.codenameone.com/blog/javadoc-source-samples-that-dont-suck.html

You can see this used in our code e.g.: https://www.codenameone.com/javadoc/com/codename1/components/MediaPlayer.html

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

来源：https://stackoverflow.com/questions/1391614/syntax-highlighting-for-javadoc

标签

java

syntax-highlighting

javadoc