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.
Best Answer
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)