We're using the Maven JavaDoc Plugin to generate javadocs for our projects. When generating the JavaDoc for some methods, the alignment is completely off. For example this produces this (spaces preserved, please don't edit them out): As you can see, it's just really annoying to read and I would prefer if it lined up, or at least if there wasn't

Maven JavaDoc Plugin outputs incorrect parameter alignment

We’re using the Maven JavaDoc Plugin to generate javadocs for our projects.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.2.0</version>
    <executions>
        <execution>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
</plugin>

JavaScript
​x
 
<plugin>    <groupId>org.apache.maven.plugins</groupId>    <artifactId>maven-javadoc-plugin</artifactId>    <version>3.2.0</version>    <executions>        <execution>            <goals>                <goal>jar</goal>            </goals>        </execution>    </executions></plugin>​

When generating the JavaDoc for some methods, the alignment is completely off. For example this

@GetMapping(value = "/api/manyToOnes/{tablePlural}/{id}", produces = MediaType.APPLICATION_JSON_VALUE)
public Map<String, String> getManyToOnes(@PathVariable String tablePlural, @PathVariable Integer id)

JavaScript
 
@GetMapping(value = "/api/manyToOnes/{tablePlural}/{id}", produces = MediaType.APPLICATION_JSON_VALUE)public Map<String, String> getManyToOnes(@PathVariable String tablePlural, @PathVariable Integer id)​

produces this (spaces preserved, please don’t edit them out):

@GetMapping(value="/api/manyToOnes/{tablePlural}/{id}",
            produces="application/json")
public Map<String,String> getManyToOnes(@PathVariable
                                                                                                                                         String tablePlural,
                                                                                                                                         @PathVariable
                                                                                                                                         Integer id)

JavaScript
 
@GetMapping(value="/api/manyToOnes/{tablePlural}/{id}",            produces="application/json")public Map<String,String> getManyToOnes(@PathVariable                                                                                                                                         String tablePlural,                                                                                                                                         @PathVariable                                                                                                                                         Integer id)​

As you can see, it’s just really annoying to read and I would prefer if it lined up, or at least if there wasn’t a huge gap in the middle.

I can’t work out exactly what it’s struggling with, but it seems to be related to the annotations. Other methods which do not use annotations are fine.

I checked the config to see if there was anything related to alignment but I didn’t see anything.

I am already using the latest version, would downgrading to a previous version help? I’m reluctant to manually iterate through them, especially when there’s no guarantee it ever worked.

I checked the issue tracker, there doesn’t seem to be anything matching what I’m seeing. If no one can help here then I’ll raise a bug there. I don’t recall seeing this in any other project’s JavaDocs, so I’m inclined to think it’s my problem rather than theirs.

Answer

Upon investigating this, I learned that it is not the plugin which generates the HTML at all, but rather it delegates this to a tool provided by the JDK, jdk/bin/javadoc.exe

After learning this, I tried building with JDK 9 rather than 8 and the output was much better.

@GetMapping(value="/api/manyToOnes/{tablePlural}/{id}",
            produces="application/json")
public Map<String,String> getManyToOnes(@PathVariable
                                        String tablePlural,
                                        @PathVariable
                                        Integer id)

JavaScript
 
@GetMapping(value="/api/manyToOnes/{tablePlural}/{id}",            produces="application/json")public Map<String,String> getManyToOnes•(@PathVariable                                        String tablePlural,                                        @PathVariable                                        Integer id)​

I looked at Oracle’s bug tracker for fixVersion = 9 which led me to the bug: JDK-8062647

FWIW I learned that the output is different from both of these in Java 12, so it seems it’s going through changes quite often.

Advertisement

Answer