United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-4317583 : stddoclet: Inherited @throws improperly copies from overridden method to subclas

Details
Type:
Bug
Submit Date:
2000-02-29
Status:
Closed
Updated Date:
2014-05-05
Project Name:
JDK
Resolved Date:
2001-07-13
Component:
tools
OS:
solaris_2.6,solaris_7,generic,windows_2000
Sub-Component:
javadoc(tool)
CPU:
x86,sparc,generic
Priority:
P4
Resolution:
Fixed
Affected Versions:
3.1.1,1.2.2,1.3.0,1.4.0
Fixed Versions:
1.4.0 (beta2)

Related Reports
Duplicate:
Duplicate:
Duplicate:
Relates:

Sub Tasks

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



Hardware and Software, Engineered to Work Together