[ https://issues.apache.org/jira/browse/MJAVADOC-387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15096802#comment-15096802 ]
Christopher Tubbs commented on MJAVADOC-387: -------------------------------------------- Technically, doclint *is documented* with {{javadoc -X}} as a nonstandard option for javadoc. OpenJDK's man page documents it as being "Provided by standard doclet". Regarding *auto*: {{-Xdoclint:auto}} is not a valid option (at least, not one documented in OpenJDK's man page or on [Oracle's docs|http://docs.oracle.com/javase/8/docs/technotes/tools/unix/javadoc.html]), so I assumed that what was meant by *auto* in [~ceefour]'s proposal was actually a parameter to the maven-javadoc-plugin to instruct it to omit the {{-Xdoclint}} option entirely (while *none* would actually map to the {{-Xdoclint:none}} option and something else, like *all,-missing* would map to {{-Xdoclint:all,-missing}}). After some thought, I think this would be a bit confusing for one string to behave differently than others. The default/automatic behavior should be provided by omitting the {{<doclint/>}} option from the plugin configuration, while passing {{<doclint>auto</doclint>}} should result in {{-Xdoclint:auto}}, which will likely just cause an error if the underlying javadoc doesn't recognize *auto* as a valid option. To summarize: * If the {{doclint/>}} option does not exist in the configuration, or is empty: ** Do nothing, regardless of JDK version * If {{<doclint/>}} exists in the configuration and has a non-empty value of {{string}}: ** If the JDK version is less than 8, issue a warning and do not provide the option to the javadoc tool ** If the JDK version is greater than or equal to 8, treat as {{-Xdoclint:string}} > Handle JDK8 -Xdoclint > --------------------- > > Key: MJAVADOC-387 > URL: https://issues.apache.org/jira/browse/MJAVADOC-387 > Project: Maven Javadoc Plugin > Issue Type: Improvement > Reporter: scolebourne2 > > The Oracle team have added the doclint tool to JDK 8. The tool validates > Javadoc as part of a standard Javadoc run. Unfortunately, with the default > settings, it rejects many HTML elements that are perfectly acceptable to > browsers, and all invalid Javadoc references (@links). This is likely to > prove very unpopular with developers. > Action needed: > 1) Provide a maven-javadoc-plugin configuration item and property that can > control the doclint tool (currently this requires using additionalparam > AFAICT). > 2) Apply the {{-Xdoclint:none}} option by default, so that doclint is opt-in, > not opt-out (ie. fix Oracle's messed up default). This will also make it much > easier for developers to handle migration to JDK 8. -- This message was sent by Atlassian JIRA (v6.3.4#6332)