JavaDoc Inheritance

Every so often you come across something so staggeringly simple and useful, yet relatively unknown. In the interests of cutting down the amount of class/method documentation we had to produce, I was researching whether people tended to document methods in interfaces, classes or both. It turns out there is a very elegant solution to give you comprehensive documentation without repeating yourself:

Document the methods in the interface, then inherit the documentation into the class, and provide fixed documentation for any class specific methods.

To let javadoc handle the inheritance from the interface, you can just comment using a tag: {@inheritDoc}. For example:

interface foo {



  /**

   * documentation!

   */

  public void x();

} 





class bar implements foo {



  /* {@inheritDoc} */

  public void x() {

    doStuff;

  }

}

One thing to note - this doesn't apply to class documentation, only to method documentation.