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)
======================================================================