3

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.

Mog
  • 141
  • 1
  • 5
  • 3
    I'm guessing you don't want to introduce an abstract class that implements the behavior? – Mike Partridge Jun 18 '13 at 15:15
  • as @MikePartridge implied, [Composition over Inheretance](http://en.wikipedia.org/wiki/Composition_over_inheritance) – Ampt Jun 18 '13 at 15:19
  • @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! :) – Mog Jun 18 '13 at 16:25
  • 1
    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. – Mike Partridge Jun 18 '13 at 16:55

1 Answers1

3

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)

Nathan Gerhart
  • 156
  • 5