maven - JDK8: Getting back the JDK7 look for javadoc

Question

I find it difficult to read the new look-and-feel in JDK8 javadoc compared to JDK7. Here's a side-by-side example.

JDK7:

JDK8:

JDK8 takes up considerable more space. It now uses the DejaVu font where Arial was previously used. There may be good reasons for that. I don't know.

My biggest problem is in the "Parameters" and "Throws" sections where there's no longer any visual difference between the argument and its description. They are both in a mono spaced font. Writing descriptive text in mono spaced font is just ugly, I think. Mono spaced font is for names of identifiers, source code listings and the like. (feel free to disagree).

Can I get the JDK7 style back while still using the JDK8 javadoc tool?

I was hoping for something like javadoc -stylesheet jdk7.css where jdk7.css was something included with the JDK8. Also if I decide to customize the css on my own (not my thing, but there may be no other solution) I would hate to have to ensure availability of the new stylesheet on every build server in our enterprise. Perhaps there's a Maven solution for that ?

POSSIBLE SOLUTION ?

It has been suggested (below) to use the JDK7 javadoc css with the JDK8 javadoc tool to see if that would bring back some eligible Javadoc.

I've done my test by checking out the source code from the Apache Commons Lang project. I use only the source code, not their POM. This is to ensure that I know I'm working off the right base.

Okay, first - for reference - here's the Javadoc which has been produced by an all JDK7 toolchain (JDK7 javadoc tool, JDK7 css). Here's the POM snippet:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>2.9.1</version>
            <configuration>
                <stylesheetfile>${basedir}/src/main/css/jdk7javadoc.css</stylesheetfile>  
                <javadocExecutable>C:/Program Files/Java/jdk1.7.0_55/bin</javadocExecutable>   
            </configuration>
        </plugin>
    </plugins>
</build>  

and the resulting Javadoc:

Next, the attempt to use the JDK7 css with the JDK8 javadoc tool. Here's the POM snippet:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>2.9.1</version>
            <configuration>
                <stylesheetfile>${basedir}/src/main/css/jdk7javadoc.css</stylesheetfile>  
                <javadocExecutable>C:/Program Files/Java/jdk1.8.0_05/bin</javadocExecutable>   
            </configuration>
        </plugin>
    </plugins>
</build>  

and the resulting Javadoc:

So, as you can see, this strategy did not work out for me.

UPDATE

I've just realized that a consequence of this change is that it has become pointless to use {@code } (or <code>) markup on parameter descriptions. It doesn't show anyway. In other words if you liked to do like this in past:

/**
* ...
* @param eName the name for the entity or <code>null</code> to use the default
* ...
*/

there's simply no point to that anymore. Your null text will not stand out anyway.

UPDATE 2019-04-19

Parts of the problems mentioned above has been fixed in JDK-8072052 : <dd> part of <dl> list in javadoc should not be in monospace font. Fixed in Java 9 onwards, not backported to Java 8.

Answer 1

The css used in Java 7's Javadoc can be found here:

http://docs.oracle.com/javase/7/docs/api/stylesheet.css

You can then use the stylesheetfile attribute from the javadoc commandline, or ant or maven

from commandline:

%javadoc -stylesheetfile <path> ...

in ant:

<javadoc 
        ....
        stylesheetfile="/path/to/stylesheet.css"
        />      

in Maven (see Maven's stylesheet configuration page for more details ):

<reporting> (or <build>)
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        ...
        <configuration>
          <stylesheetfile>${basedir}/path/to/your/stylesheetfile.css</stylesheetfile>
          ...
        </configuration>
      </plugin>
    </plugins>
    ...
  </reporting> (or </build>) 

UPDATE

Stephen Colebourne has an article about other breaking changes to Javadoc in Java 8 here . Apparently, the doclint now enforces HTML 4 compliance and will not link if the link is broken or not 100% correct HTML 4. You can turn it off with -Xdoclint:none as an additional parameter.

<plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <configuration>
        <additionalparam>-Xdoclint:none</additionalparam>
      </configuration>
    </plugin>
 </plugins>

Regarding the <code> tags in parameter descriptions, I did see that too. It looks like the parameter descriptions in javadoc are now always monospace so you don't need code tags anymore?