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.

Improve this question
4
  • 3
    I'm guessing you don't want to introduce an abstract class that implements the behavior?
    – Mike Partridge
    Commented Jun 18, 2013 at 15:15
  • as @MikePartridge implied, Composition over Inheretance
    – Ampt
    Commented Jun 18, 2013 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
    Commented Jun 18, 2013 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
    Commented Jun 18, 2013 at 16:55

1 Answer 1

Reset to default
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)

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.