FULL PRODUCT VERSION :
Linux:
java version "1.8.0_25"
Java(TM) SE Runtime Environment (build 1.8.0_25-b17)
Java HotSpot(TM) 64-Bit Server VM (build 25.25-b02, mixed mode)
Windows:
java version "1.8.0_25"
Java(TM) SE Runtime Environment (build 1.8.0_25-b18)
Java HotSpot(TM) 64-Bit Server VM (build 25.25-b02, mixed mode)
ADDITIONAL OS VERSION INFORMATION :
Linux laptop.home 3.16.5-gentoo #1 SMP Sat Nov 29 06:48:35 CET 2014 x86_64 Intel(R) Core(TM) i7-4771 CPU @ 3.50GHz GenuineIntel GNU/Linux
Microsoft Windows [Version 6.3.9600] (Windows 8.1)
A DESCRIPTION OF THE PROBLEM :
When a method in an interface has multiple @throws tags in its JavaDoc comment, the generated HTML for that interface lists the exception multiple types, once for each provided reason why this exception could occur.
If this interface is then implemented by a class, and no additional JavaDoc is provided, the JavaDoc from the interface is copied to the class. In the generated HTML for the class however, only the first @throws tag for each exception type is listed, discarding any other exceptions of the same type (and their description)
STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
1. Create interface with a method that has two or more @throws tags in its javadoc with the same Exception type
2. Create a class that implements this interface, with @Override annotations, but no new javadoc, to ensure the documentation is copied over
3. Run the javadoc tool on the interface and class
EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
The generated HTML for both the interface and the class should contain all throws clauses specified in the javadoc comment
ACTUAL -
The generated HTML for the interface showed the correct exception information, the generated HTML for the class only showed the first exception of each type.
REPRODUCIBILITY :
This bug can be reproduced always.
---------- BEGIN SOURCE ----------
File: com/example/bug/Interface.java
package com.example.bug;
public interface Interface {
/**
* Method that foos a bar.
* @throws IllegalArgumentException if foo is null
* @throws IllegalArgumentException if bar is null
*/
public void method(String foo, String bar) throws IllegalArgumentException;
}
File: com/example/bug/Foo.java
package com.example.bug;
public class Foo implements Interface {
@Override
public void method(String foo, String bar) throws IllegalArgumentException {
if (foo == null) {
throw new IllegalArgumentException("foo must not be null");
}
if (bar == null) {
throw new IllegalArgumentException("bar must not be null");
}
}
}
---------- END SOURCE ----------
CUSTOMER SUBMITTED WORKAROUND :
Specifying all exceptional cases that result in a single exception type in a single description is doable, but not desirable