JDK-4778311 : stddoclet: @param in base class is ignored if {@inheritDoc} in main description
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.4.1
  • Priority: P4
  • Status: Resolved
  • Resolution: Won't Fix
  • OS: linux,windows_98
  • CPU: x86
  • Submitted: 2002-11-13
  • Updated: 2014-05-05
  • Resolved: 2014-01-09
Description

Name: gm110360			Date: 11/13/2002


FULL PRODUCT VERSION :
C:\Java>java -version
java version "1.4.1_01"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.1_01-b01)
Java HotSpot(TM) Client VM (build 1.4.1_01-b01, mixed mode)


FULL OPERATING SYSTEM VERSION : Windows ME


A DESCRIPTION OF THE PROBLEM :
@param tag in the sub class is ignored.

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
1. Try to generate a javadoc with the sample above
2.
3.

EXPECTED VERSUS ACTUAL BEHAVIOR :
@param tag in the sub class should be reflected in a
generated HTML file. But @para tag in the base class is
copied into the generated HTML files.

REPRODUCIBILITY :
This bug can be reproduced always.

---------- BEGIN SOURCE ----------
abstract class InheritDocBase {
    /**
     * Return the last name of persons whose first name is matched.
     *
     * @param   firstName firstName to be searched
     * @return  array of last names
     * @throws  java.lang.Exception name not found
     */
     public abstract String[] geLastName(String firstName) throws Exception;
}


class InheritDocSub extends InheritDocBase {
    /**
     * Based on the address book, {@inheritDoc}
     *
     * @param   firstName first Name to be searched from the address book.
     */
     public abstract String[] geLastName(String firstName) throws Exception;
}
---------- END SOURCE ----------
(Review ID: 166857) 
======================================================================

Name: rmT116609			Date: 02/27/2003


DESCRIPTION OF THE PROBLEM :
Using {@inheritDoc} in a method comment overrides the @param
tag.

The {@inheritDoc} should only add text, not override any,
and it shouldn't affect tags that don't contain it.

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
1. javadoc SuperClass.java SubClass.java

EXPECTED VERSUS ACTUAL BEHAVIOR :
SubClass METHOD DETAIL contents:

expected:
Parameters:
bar - subclass doc bar

actual:
Parameters:
bar - superclass doc bar

REPRODUCIBILITY :
This bug can be reproduced always.

---------- BEGIN SOURCE ----------
public class SuperClass {
        /**
         * First sentence from superclass.  Second sentence from superclass.
         * @param bar superclass doc bar
         */
        public void foo( int bar ) {}
}

public class SubClass extends SuperClass {
        /**
         * {@inheritDoc} First sentence from subclass.  Second sentence from
subclass.
         * @param bar subclass doc bar
         */
        public void foo( int bar ) {}
}

---------- END SOURCE ----------


(Review ID: 181838)
======================================================================

Comments
Works as expected and the contract of a supertype must be met in any subtype.
2014-01-09

CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: dragon
2004-06-14

EVALUATION I am able to reproduce this bug. The @param text in the subclass should appear in the generated HTML for the subclass, but does not. The @param text for the base class appears instead. This is a bug, as this should happen only if the subclass either has no @param text or has "@param {@inheritDoc}". Changed synopsis from: @param tag is not handled correctly to: @param in base class is ignored if {@inheritDoc} in main description ###@###.### 2002-11-13 Yoshiki wrote: But, I think, the bug is not a big problem, because usually the contract of a supertype must be met in any subtype and explanations of parameters will not be altered in a subtype. ###@###.### 2002-11-13
2002-11-13