JDK-4802275 : @param should be printed even if first argument is incorrect - REGRESSION
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.4.0
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • OS: other
  • CPU: generic
  • Submitted: 2003-01-13
  • Updated: 2014-05-05
  • Resolved: 2003-11-23
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
5.0 b30Fixed
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:

   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.

CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: tiger tiger-beta FIXED IN: tiger-beta INTEGRATED IN: tiger-b30 tiger-beta

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

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