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.

• Mike Partridge: I'm guessing you don't want to introduce an abstract class that implements the behavior?
• Ampt: as @MikePartridge implied, Composition over Inheretance
• Mog: @MikePartridge: I'm not sure of what you're proposing. This behavior depends on the classes and I'd like the interface to stay static. I'm certainly missing your point so please extend your suggestion! :)
• Mike Partridge: My question refers to creating an abstract class that implements your interface which would become a parent of your various implementations. The abstract class could define the load method and house the javadoc for it. As @Ampt suggested however, you could also extract the load logic to a static class which your implementations would delegate to, and your interface would then contain a link to the static class's load method documentation. This would avoid inheritance.

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)