Javadoc for a static “overloaded” method

Question

My problem is the following:

I have an interface that requires its implementations to implement a static method, namely void load(). However, until Java 8, it seems we won't get static methods in interfaces. I trust my users to still implement it correctly, but my problem is how to write a proper doc.

There are up to 50 implementations of this interface and not being able to inherit the javadoc is a bother.

What is the best way to proceed in my case? Should I document a random implementation and add @see annotations in the others? It seems dirty to me.

Any suggestion is welcome.

Answer 1

As you stated, there isn't a way (until Java 8) for an interface to require a static method. There also isn't a way to override a static method, so which documentation could actually be inherited?

I see a few options:

• If the documentation on the interface describes the method (which I would expect - how are implementers supposed to know about the load() method?), have the docs of all implementations link to it:

  /** required static method as expected by {@link Loadable} */

• If there is a sane default implementation for the load() method, put it in an abstract class implementing the interface and have the docs for all implementations link to it (rather than just a random implementation):

  /** @see AbstractLoadable#load() */

• Extract the polymorphic functionality in the load() method to a non-static method. The interface can then explicitly require the new method, and javadoc will automatically inherit the documentation from the interface. (I realize this might not be a viable option)