JDK-4317583 : stddoclet: Inherited @throws improperly copies from overridden method to subclas
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 3.1.1,1.2.2,1.3.0,1.4.0
  • Priority: P4
  • Status: Closed
  • Resolution: Fixed
  • OS: generic,solaris_2.6,solaris_7,windows_2000
  • CPU: generic,x86,sparc
  • Submitted: 2000-02-29
  • Updated: 2014-05-05
  • Resolved: 2001-07-13
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availabitlity Release.

To download the current JDK release, click here.
Other
1.4.0 beta2Fixed
Related Reports
Duplicate :  
Duplicate :  
Duplicate :  
Relates :  
Description
When an overriding method's doc comment doesn't contain any javadoc tags, 
the standard doclet copies the javadoc tags from the overridden methods 
doc comment in the superclass.  In some cases, this results in copying 
@throws tags to the overriding method in the subclass when the subclass's 
method doesn't throw any exceptions.

An example of this is the java.io.PrintWriter.write(int) spec.
 http://webwork.eng/products/jdk/1.3/docs/api/java/io/PrintWriter.html#write(int)

PrintWriter.write(int) overrides Writer.write(int), and PrintWriter.write's spec copies the @throws IOException tag from Writer.write's spec.  However, this is 
not appropriate since PrintWriter.write does not throw IOException.  

The standard doclet should not blindly copy javadoc tags, or at least @throws 
tags, to the overriding class's spec.

This problem is present in 1.2.2 and 1.3.

Comments
CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: merlin-beta2 FIXED IN: merlin-beta2 INTEGRATED IN: merlin-beta2 VERIFIED IN: merlin-rc1
2004-06-14

WORK AROUND This problem can be avoided by adding some javadoc tags to the overriding method's doc comments so that no tags are copied from the overridden class.
2004-06-11

EVALUATION This causes the spec to be wrong. We need to consider how to fix this. doug.kramer@Eng 2000-09-07 This is closely related to RFE 4186639, which asks for @inheritdoc tag to explicitly inherit documentation. I do not consider them dupes and am keeping them separate since one is a bug and the other a feature request. This bug is more pressing to fix, and may be the impetus for the RFE to be implemented. doug.kramer@Eng 2000-11-15 The doclet no longer copies throw tags from overridden methods. (Merlin Beta 2) The user will be able to explicitely inherit the documentation when RFE 4816639 is implemented. Location of fix: MethodSubWriter.java jamie.ho@Eng 2001-05-29 The behaviour of @throws tag inheritence has been improved. We now allow @throws tags for declared exceptions to be inherited from the overriden or implemented method. (Merlin Beta 3) Location of fix: com/sun/tools/doclets/standard/tags/ThrowsTaglet.java ###@###.### 2001-09-06
2001-09-06

PUBLIC COMMENTS This bug has been fixed. The doclet no longer copies throw tags from overridden methods. jamie.ho@Eng 2001-05-29 The behaviour of @throws tag inheritence has been improved. We now allow @throws tags for declared exceptions to be inherited from the overriden or implemented method. ###@###.### 2001-09-06
2001-09-06