Since Java 8, javadoc doclint became a lot stricter. Up to now, we had some warnings here and there. But since we moved to Java 8, our Jenkins releases are failing because doclint would throw HTML parsing errors and stop the build. So I spent some time to correct those errors. I was thinking that it might not be such a bad idea to have correct javadoc after all.
Except that recently, we had to access a WebService in SOAP. So I used the tool provided with the JDK: wsimport. Not a bad tool, it really provides nice javadoc. But doclint would just not like it. It does not like <p> tags without their matching close tag. It would not like the <pre> tags, or rather what would go right after it, which is something that browsers should not interpret. In short, doclint makes an other JDK tool to fail at its job. So I resorted to Stephen Colebourne's advice: I switched off doclint altogether. In our maven configuration, it looks like that:
<plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-javadoc-plugin</artifactId><configuration><additionalparam>-Xdoclint:none</additionalparam></configuration></plugin></plugins>