Java - Convention for using javadoc along with a method annotation?

Question

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
   }

Solution 1

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.

Solution 2

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.

Comments

[buc]

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.

[Markus]

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.