United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-4802275 @param should be printed even if first argument is incorrect - REGRESSION
JDK-4802275 : @param should be printed even if first argument is incorrect - REGRESSION

Details
Type:
Bug
Submit Date:
2003-01-13
Status:
Resolved
Updated Date:
2004-01-24
Project Name:
JDK
Resolved Date:
2003-11-23
Component:
docs
OS:
other
Sub-Component:
doclet
CPU:
generic
Priority:
P3
Resolution:
Fixed
Affected Versions:
1.4.0
Fixed Versions:
5.0 (b30)

Related Reports

Sub Tasks

Description
When a doc comment is written, the first argument to @param should match one of
the method parameters.  In 1.4.2, if it does not match in spelling and case,
then @param is not printed.  This causes important parts of the spec to
disappear when a user upgrades to 1.4.  This is a mistake, and is contrary to 
how javadoc worked prior to 1.4.  

Instead @param should be printed with the misspelled argument, as in most cases,
the user can correlate the misspelled @param argument to the correct method
parameter, and benefit from reading the @param description.

For example, in constructor BeansContextServicesSupport:

    /**
     * ...
     * @param dtime The initial state, true if in design mode, false if runtime.
     * ...
     */
    public BeanContextServicesSupport(BeanContextServices peer, Locale lcle, boolean dTime, boolean visible) {
	super(peer, lcle, dTime, visible);
    }

The first argument "dtime" is not capitalized properly, so neither it nor
its description is printed.  It should be printed as-is.
Here is the parameter printout:

Parameters:
   peer - The peer BeanContext we are supplying an implementation for, 
      if null the this object is its own peer
   lcle - The current Locale for this BeanContext.
   visible - The initial visibility.

This is the current warning for the above error:

/java/pubs/ws/mantis/make/docs/../../src/share/classes/java/beans/beancontext/BeanContextServicesSupport.java:59: warning - @param argument "dtime" is not a parameter name.

                                    

Comments
EVALUATION

Important, as it prevents part of the spec from printing.
###@###.### 2003-01-13

Fixed.
###@###.### 2003-11-15
                                     
2003-01-13
PUBLIC COMMENTS

Fixed.  We still warn when the @param does not match with a real parameter, but we now include it in the output.
###@###.### 2003-11-15
                                     
2003-11-15
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
tiger
tiger-beta

FIXED IN:
tiger-beta

INTEGRATED IN:
tiger-b30
tiger-beta


                                     
2004-06-14



Hardware and Software, Engineered to Work Together