United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-4693440 : Does not warn when first argument of @param is not parameter name

Details
Type:
Bug
Submit Date:
2002-05-30
Status:
Resolved
Updated Date:
2014-05-05
Project Name:
JDK
Resolved Date:
2002-09-02
Component:
tools
OS:
windows_2000
Sub-Component:
javadoc(tool)
CPU:
x86
Priority:
P3
Resolution:
Fixed
Affected Versions:
1.4.0
Fixed Versions:
1.4.2 (mantis)

Related Reports

Sub Tasks

Description

Name: gm110360			Date: 05/29/2002


FULL PRODUCT VERSION :
java version "1.4.0"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.0-b92)
Java HotSpot(TM) Client VM (build 1.4.0-b92, mixed mode)

FULL OPERATING SYSTEM VERSION :win 2000


A DESCRIPTION OF THE PROBLEM :
Running javadoc 1.4 on below program does not generate
@params (see source code below)


REGRESSION.  Last worked in version 1.3

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
1.cut and a paste the source code into test.java
2.get into jdk 1.4 environment
3.do javadoc test.java and see the output

EXPECTED VERSUS ACTUAL BEHAVIOR :
The expected result should be like result of jdk1.3
javadoc.

This bug can be reproduced always.

---------- BEGIN SOURCE ----------
public class test
{
  /**
   * Show the problem with javadoc 1.4.
   * Javadoc 1.4 does not generate the @param.
   *
   * @param String -name
   * @param int -age
   * @return boolean -true is age is less than 13, false otherwise.
  */
  public int test(String name, int age)
    throws Exception
  {
    if ( age < 13 ) return true;
    return false;
  }
}
---------- END SOURCE ----------

CUSTOMER WORKAROUND :
Have not find one yet.

Release Regression From : 1.3.1_03
The above release value was the last known release where this 
bug was known to work. Since then there has been a regression.

(Review ID: 147172) 
======================================================================

Comments
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
mantis
mantis-b02

FIXED IN:
mantis
mantis-b02

INTEGRATED IN:
mantis
mantis-b02
2004-06-14 
PUBLIC COMMENTS

I have fixed this bug.  When a bad parameter name is passed to @param, the following warning is printed:

@param argument "paramName" is not a parameter name.

When @param is used more than once for the same parameter, the following warning is printed:

 Parameter "paramName" is documented more than once.

###@###.### 2002-07-18
2002-07-18 
EVALUATION

What is happening here is that starting with 1.4.0, the @param tag requires 
its first argument to be the parameter name.  In this case, the user has 
specified the parameter type instead.

Prior to 1.4.0, the test method parameters were documented as:

Parameters:
            name - -String
            age - -int

With 1.4.1, however, the Parameters heading and entries are missing altogether,
with no warning.  Javadoc should print a warning when the parameter
name specified by @param does not appear in the declaration's 
parameter list.  

Suggest a warning such as (of course, the filename and line number
should be included):

   warning: @param argument "String" is not a parameter name

Committed to mantis.

Changed synopsis from:
  javadoc does not generate @param
to this:
  Does not generate @param when its first arg is not parameter name

###@###.### 2002-05-30

Changed synopsis from:
  Does not generate @param when its first arg is not parameter name
to this:
  Does not warn when first argument of @param is not parameter name

Removed "REGRESSION" from synopsis, as not generating @param when there
is a mismatch is a new feature.

###@###.### 2002-05-31

This bug fix should also handle the case where there is an extra @param
tag listed, as the first arg to @param would not correspond to a parameter name.
This was discussed on the Javadoc Forum subject "@param".  For example:

public class ParamBug {

   /**
    * Space pad a String.
     @param S String to pad.
     @param length Desired minimum length.
     @param end Should the padding be at the end.
     @param extra the extra param
    */
    public static String pad(String S, int length, boolean end) {
    }
}


###@###.### 2002-05-31

I have fixed this bug. The bug fix is pending review.
###@###.### 2002-07-08
2002-05-31


Hardware and Software, Engineered to Work Together