如何排除部分文档注释显示在生成的 Javadoc 中答案

【问题标题】：How to exclude part of doc comment from being displayed in generated Javadoc如何排除部分文档注释显示在生成的 Javadoc 中
【发布时间】：2016-10-25 11:32:56
【问题描述】：

在我们的项目中，我们将编写 API javadocs。在 doc cmets 中，除了方法细节之外，我们还想写历史细节。例如，如果为了修复特定问题而修改了方法，我们希望记录问题的详细信息以及该方法的 javadoc 注释。

/**
 * Displays the details for a valid registered customer against the specified <code>Integer customerId</code>.<br>
 * Responsible to check the existance of the customer before sending back the information for the "Customer Reference" screen.
 * 
 * @param customerId the customer id to fetch the details for
 * @return <code>jsp</code> file name for "Customer Reference" screen along with Customer details
 * 
 * BTS-1947 | custom fields not displayed correctly | 25-10-2016 | Vaibhav
 */
public String displayCustomerInfo(Integer customerId) {

问题是，我们不想在使用 javadocs 工具生成的 javadocs 中显示 BTS-1947 | custom fields not displayed correctly | 25-10-2016 | Vaibhav 部分。是否可以这样做，或者有没有更好的方法来使用 javadocs 维护更新历史记录？

【问题讨论】：

该评论对您的源代码管理历史有什么价值？
我也有同样的感觉，但我被要求为此提供解决方案，因为我的经理希望其他开发人员通过查看代码本身而不是源代码控制历史来了解历史（在我们的例子中是 SVN） .我们为历史部分写了普通的多行注释 /*...*/ 但这看起来不太好写两种不同类型的 cmets 一个在另一个之上。
为什么不将该信息放在 javadoc 正上方的另一个非 javadoc 注释上？
这就是我目前正在做的，因为到目前为止我还没有找到任何其他解决方案。

标签： java javadoc

【解决方案1】：

如果您使用的是 jdk1.7，您可以使用自定义标签。当 javadoc 编译时，它不会显示任何带有自定义标记的内容。它会给你一个警告。例如：

/**
* Displays the details for a valid registered customer against the specified <code>Integer customerId</code>.<br>
* Responsible to check the existance of the customer before sending back the information for the "Customer Reference" screen.
* 
* @param customerId the customer id to fetch the details for
* @return <code>jsp</code> file name for "Customer Reference" screen along with Customer details
* 
* @custom BTS-1947 | custom fields not displayed correctly | 25-10-2016 | Vaibhav
*/
public String displayCustomerInfo(Integer customerId) {

jdk1.8 在编译带有自定义标签的 javadoc 时会报错。

希望这有帮助，请告诉我。

【讨论】：

您好@observer，感谢您的回复。但我们使用的是 JDK 1.8。