All methods should have a Javadoc comment

[cclarke]

I'm having some trouble with the "All methods should have a Javadoc comment" rule.

1) For the "compareTo" method within the Comparable interface, a single non-Javadoc comment is flagged. "Allow non-javadoc comments with only a single @see tag" is checked.

2) For the "compareTo" method within the Comparable interface, if I change the comment to be a Javadoc comment with just a single @see comment I then get a violation for "missing @return tag" and "missing @param tag". It seems the "Check @param tags" and "Check @return tags" settings argue with the "Allow comments with only a single @see tag" setting.

[Brian Wilkerson]

I tried to duplicate the behavior you were seeing, but was not successful. If I create the following class

Code: Select all

   public static class Value implements Comparable
   {
      /**
       * @see Comparable#compareTo(Object)
       */
      public int compareTo(Object o) {
         return 0;
      }
   }


and audit it, I don't get an violations. I have the rule configured to

• check for all visibilities,
• check for @param, @return, and @throws tags,
• allow @throws tags for unchecked exceptions, and
• allow comments with only a single @see tag.

The "Allow comments with only a single @see tag" options supports Javadoc comments, so yes, it will flag non-Javadoc comments. This was added to support an Eclipse style of commenting overriding methods.

If you're still seeing violations when your comments look like the one above, please send me a sample that I can use for testing and/or let me know what's different between our configurations. Thanks.

[cclarke]

I have the rule configured as:

check for all visibilities
check for @param, @return, and @throws tags
allow @throws tags for unchecked exceptions
allow comments with only a single @see tag
allow non-javadoc comments with only a single @see tag

For the non-Javadoc rule try this:

Code: Select all

public class Value
   implements Comparable<Value>
{
   /* (non-Javadoc)
    * @see Comparable#compareTo(Object)
    */
   public int compareTo(Value o)
   {
      return 0;
   }
}


For the Javadoc rule try this:

Code: Select all

public class Value
   implements Comparable<Value>
{
   /**
    * @see Comparable#compareTo(Object)
    */
   public int compareTo(Value o)
   {
      return 0;
   }
}


[cclarke]

Ah...never mind. The @see is incorrect. Should be @see Comparable#compareTo(Value).

[Eric Clayberg]

Glad you found the problem.