United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-4496270 : stddoclet: @param and @return are not always copied down from supertype

Details
Type:
Bug
Submit Date:
2001-08-24
Status:
Closed
Updated Date:
2014-05-05
Project Name:
JDK
Resolved Date:
2001-10-09
Component:
tools
OS:
generic
Sub-Component:
javadoc(tool)
CPU:
generic
Priority:
P3
Resolution:
Fixed
Affected Versions:
1.4.0
Fixed Versions:
1.4.0 (beta3)

Related Reports

Sub Tasks

Description
In the following example, the method description is copied down, but the @param and @return are not. This appears to be contrary to the documentation.

package jd;

public class JD {
    /** 
     * description
     *
     * @param o object
     * @return value
     * @throws IOException because
     */
    public boolean foo(Object o) throws java.io.IOException {
	return false;
    }

    public static class Bar extends JD {
	/**
	 * @throws IOException why not
	 */
	public boolean foo(Object o) throws java.io.IOException {
	    return false;
	}
    }
}

                                    

Comments
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
merlin-beta3

FIXED IN:
merlin-beta3

INTEGRATED IN:
merlin-beta3

VERIFIED IN:
merlin-beta3


                                     
2004-06-14
EVALUATION

This bug is high on our priority list and will be fixed soon.  We will also follow the recommendation that you gave for bug 4317583: 

"Please consider inheriting @throws for all exceptions that the subclass
does in fact declare, and preferably inheriting @throws for all runtime
exceptions as well."

We agree with this.

###@###.### 2001-08-24

This bug has been fixed.  Location of fix:

com/sun/tools/doclets/standard/tags/AbstractExecutableMemberTaglet.java
com/sun/tools/doclets/standard/tags/ParamTaglet.java
com/sun/tools/doclets/standard/tags/ReturnTaglet.java
com/sun/tools/doclets/standard/tags/SeeTaglet.java
com/sun/tools/doclets/standard/tags/ThrowsTaglet.java

###@###.### 2001-09-06
                                     
2001-09-06
PUBLIC COMMENTS

In the following example, the method description is copied down, but the @param and @return are not. This appears to be contrary to the documentation.

package jd;

public class JD {
    /** 
     * description
     *
     * @param o object
     * @return value
     * @throws IOException because
     */
    public boolean foo(Object o) throws java.io.IOException {
	return false;
    }

    public static class Bar extends JD {
	/**
	 * @throws IOException why not
	 */
	public boolean foo(Object o) throws java.io.IOException {
	    return false;
	}
    }
}

This bug has been fixed.  We previously had an "all or nothing rule":

-Copy all of the inherited tags from the overriden or implemented method if no tag documentation exists.
-Don't copy any inherited tags if any tag documentation exists.

We now look at each tag (@param, @return, @throws) individually and copy each one when needed.  Please note that we still have an "all or nothing" rule for @see tags.  Furthermore, only @throws tags for declared exceptions are inherited. 
###@###.### 2001-09-06
                                     
2001-09-06



Hardware and Software, Engineered to Work Together