您很快就会意识到,就Javadoc而言,JDK8更为严格(默认情况下)。(链接 -参见最后一个要点)
如果您从不生成任何Javadoc,那么您当然不会遇到任何问题,但是Maven发布过程之类的内容以及您的CI构建可能会突然失败,因为它们在JDK7上可以正常使用。现在,任何检查Javadoc工具的退出值的操作都将失败。warnings
与JDK7相比,JDK8 Javadoc可能也更冗长,但这不是这里的范围。我们正在谈论errors
!
存在此问题是为了收集有关如何处理的建议。最好的方法是什么?这些错误是否应该在源代码文件中一劳永逸地解决?如果您有庞大的代码库,则可能需要做很多工作。还有哪些其他选择?
也欢迎您评论以前失败的失败案例。
现在失败的恐怖故事
wsimport工具
wsimport
工具是用于创建Web服务使用者的代码生成器。它包含在JDK中。即使您使用wsimport
JDK8中的工具,它仍然会产生无法使用JDK8中的javadoc编译器进行编译的源代码。
@author标签
我正在打开3-4岁的源代码文件,并看到以下内容:
/**
* My very best class
* @author John <john.doe@mine.com>
*/
现在由于<字符而失败。严格来说,这是合理的,但不是很宽容。
HTML表格
您的Javadoc中的HTML表?考虑以下有效的HTML:
/**
*
* <table>
* <tr>
* <td>Col1</td><td>Col2</td><td>Col3</td>
* </tr>
* </table>
*/
现在,此操作将失败,并显示错误消息no summary or caption for table
。一种快速的解决方法是这样做:
/**
*
* <table summary="">
* <tr>
* <td>Col1</td><td>Col2</td><td>Col3</td>
* </tr>
* </table>
*/
但是为什么这一定是Javadoc工具引起的世界性错误呢?
现在由于更明显的原因而失败的事情
- 无效的链接,例如
{@link notexist}
- 格式错误的HTML,例如
always returns <code>true<code> if ...
更新
链接:
-Xdoclint
甚至可以使用javac
告诉它在编译时检查文档…