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>

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)

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)

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)

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.