20

I have the following method:

   @Override
   public boolean myMethod()
   {
      // do stuff
   }

If I want to add a javadoc for this method, is there any convention on how to do this along with having the @Override annotation (or any other annotation)?

The reason I ask is because I've read that javadoc comments MUST be directly before the method (no newlines between the two), and I'm not sure if putting the javadoc comment directly above the @Override annotation would mess things up.

Would this be the conventional way to do it for instance? Does this work?

   /**
    * This is my method's javadoc comment.
    */
   @Override
   public boolean myMethod()
   {
      // do stuff
   }
Tim
  • 4,295
  • 9
  • 37
  • 49
  • 5
    There's always one of you. I wanted to know what the convention was, not JUST whether it worked. – Tim Mar 25 '12 at 21:03

2 Answers2

22

Yes, this way is the right way, I didn't see yet the other way around. And yes, this way it works. Didn't try the other way around.

   /**
    * This is my method's javadoc comment.
    */
   @Override
   public boolean myMethod()
   {
      // do stuff
   }

But basically I usually wouldn't add a javadoc comment to a method that overrides another method, especially when implementing interfaces. The tag @inheritDoc is helpful here, to distribute the documentation without big efforts. But that is specific to this example, you might add other annotations, too.

Markus
  • 2,071
  • 4
  • 22
  • 44
  • I disagree that overridden methods should not be documented. This may be true with implemented interface methods, but the documentation of the overridden class methods could state what changed in the behaviour of the method. Of course, much typing can be avoided by using the `@inheritDoc` Javadoc-tag, but IMO documentation should not be left out on overridden methods. – buc Mar 25 '12 at 20:15
  • 4
    Basically I agree with you, updated my answer therefore a bit. But I think javadoc is for documenting **what** a method does and not **how** it is done. Changing the way how something is done is perfectly fine, but such a change should not violate the contract defined by the superclass which would lead to a need to change the javadoc then. This is why I think writing a javadoc for every method is not necessary. – Markus Mar 25 '12 at 20:25
3

Yes, it will work correctly. For example, in the source code of java.lang.String from openjdk, they are using javadoc on top of the @Deprecated annotation.

Tudor
  • 61,523
  • 12
  • 102
  • 142