How to exclude part of doc comment from being displayed in generated Javadoc

Question

In our project, we are going to write the API javadocs. In the doc comments apart from the method details we want to write the history details. For example, if a method was modified for fixing a particular issue, we want to document the details of the issue along with the javadoc comment for that method.

/**
 * 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) {

The problem is, we do not want to display the part BTS-1947 | custom fields not displayed correctly | 25-10-2016 | Vaibhav BTS-1947 | custom fields not displayed correctly | 25-10-2016 | Vaibhav BTS-1947 | custom fields not displayed correctly | 25-10-2016 | Vaibhav in the generated javadocs with javadocs tool. Is it possible to do so or is there a better way to maintain the update history with javadocs?

Answer 1

If you are using jdk1.7 you can use a custom tag. When javadoc compiles, it doesn't show anything with a custom tag. It will give you a warning though. For example:

/**
* 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 will give error while compiling javadoc with custom tag.

Hope this helps, let me know.