United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-4490068 stddoclet: doesn't warn for @return tag on void method
JDK-4490068 : stddoclet: doesn't warn for @return tag on void method

Details
Type:
Bug
Submit Date:
2001-08-09
Status:
Resolved
Updated Date:
2003-11-11
Project Name:
JDK
Resolved Date:
2003-11-11
Component:
docs
OS:
generic
Sub-Component:
doclet
CPU:
generic
Priority:
P4
Resolution:
Fixed
Affected Versions:
1.4.0
Fixed Versions:
5.0 (b28)

Related Reports

Sub Tasks

Description

Name: bsC130419			Date: 08/09/2001


(This goes for all versions, I believe)

When I "javadoc" a class that contains a void method, and my comment for that
method contains a @return tag, I would very much appreciate javadoc to warn me
about the mismatch.

Example:

javadoc the following code:

public class MismatchExample {

  /**
   * Here is a comment. See how it tells you what input this method
   * needs and what objects it returns, although we're dealing with
   * a method that is <i>void</i>, and that takes <i>no</i> input
   * parameters.
   *
   * @param s a mysterious string.
   * @param i a virtual integer.
   *
   * @return An object representing the world as we know it.
   */
  public void mismatch() {
    System.out.println("This method does nothing.");
  }

}

The javadoc tool doesn't complain, and the result you get is a perfectly valid
HTML page describing MismatchExample and its mismatch method. This kind of
mismatching javadoc comments happen every time one changes a method. So I'd
very much like javadoc to say something like this:

WARNING: comment for method mismatch reports more input objects than method
requires.
WARNING: method mismatch is void, but there's a @return tag in it's comment.

...and of course, it would be nice to be able to turn this feature on and off...
(Review ID: 129672) 
======================================================================

                                    

Comments
EVALUATION

We've decided to put doc comment checking in DocCheck.  I've requested
Eric:

Does DocCheck test for the absence of @return for methods
that return void?

I'm sure DocCheck does the latter request, to point out
when @param exists for a non-existant parameter.

###@###.### 2002-03-21

Fixed.
###@###.### 2003-10-11
                                     
2002-03-21
PUBLIC COMMENTS

Fixed.
###@###.### 2003-10-11
                                     
2003-10-11
WORK AROUND



Name: bsC130419			Date: 08/09/2001


None.
======================================================================
                                     
2004-06-11
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
tiger
tiger-beta

FIXED IN:
tiger
tiger-beta

INTEGRATED IN:
tiger-b28
tiger-beta


                                     
2004-06-14



Hardware and Software, Engineered to Work Together