JDK-4490068 : stddoclet: doesn't warn for @return tag on void method
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.4.0
  • Priority: P4
  • Status: Resolved
  • Resolution: Fixed
  • OS: generic
  • CPU: generic
  • Submitted: 2001-08-09
  • Updated: 2014-05-05
  • Resolved: 2003-11-11
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 Availabitlity Release.

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

WORK AROUND Name: bsC130419 Date: 08/09/2001 None. ======================================================================
2004-06-11

PUBLIC COMMENTS Fixed. ###@###.### 2003-10-11
2003-10-11

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