Javadoc Documentation Inheritance

Author: Kasper B. Graversen, 21/07/08 Keywords: Documentation, Javadoc, Inheritance Abstract: Documentation inheritance? It sounds like an idea from a person on drugs with a serious sleep deprivation. Never the less, it turns out in practice to be an approach to increase documentation coverage, while at same time reduce problems with documentation duplication and inconsistently updated documentation.

subscribe to my RSS feed

Javadoc Documentation Inheritance

• It's easy to inherit documentation and it can be automated in most IDE's
• It reduces documentation duplication.
• And best of all, it keeps the documentation coverage high, making me appear to be diligent.

How to inherit Javadoc documentation

Simple documentation inheritance

/**
 * this is some doc
 */
interface I1 {
  /**
   * this is the doc for m FROM I1
   *
   * @param a this is some parameter
   * @param b this is another parameter
   */
  void m(int a, int b);
}

class JustImplementing implements I1 {
  public void m(int a, int b) { ... }
}

/**
 * {@inheritDoc} doesn't have any effect here!
 */
class JustInherit implements I1 {
  /** {@inheritDoc} */
  public void m(int a, int b) { ... }
}

class ExtendInherited implements I1 {
  /**
   * This is the sub part I
   * <p>
   * {@inheritDoc}
   * <p>
   * And this is the sub part II
   */
  public void m(int a, int b) { ... }
}

Overriding parts of the documentation

class InheritAndChangingParts implements I1 {
  /**
   * {@inheritDoc}
   *
   * @param a new documentation for the param a only
   */
  public void m(int a, int b) {...}
}

Documentation inheritance in multiple inheritance situations

• First documentation in super classes are chosen.
• If no documentation is found, choose one from the interface. Priority is given to the interfaces in the order they are specified implemented.

/**
 * this is some doc
 */
interface I2 {
  /**
   * this is the doc for another m FROM I2
   *
   * @param a parameter2
   * @param b another parameter2
   */
  void m(int a, int b);
}

Super classes are prioritized over interfaces

class SomeSuperClass {
  /** some super documentation */
  public void m(int a, int b) {...}
}

class MultipleDocInheritance extends SomeSuperClass implements I1 {
  /** {@inheritDoc} */
  public void m(int a, int b) { ...}
}

Interface ordering and documentation inheritance

class InheritingDocFromI1 implements I1, I2 {
  /** {@inheritDoc} */
  public void m(int a, int b) {...}
}

class InheritingDocFromI2 implements I2, I1 {
  /** {@inheritDoc} */
  public void m(int a, int b) {...}
}

Automating inheritance in Eclipse

Javadoc traps

References

• A list of Javadoc tags in Java 5 http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#javadoctags
• J. Sametinger, 1994, Object-Oriented Documentation
• K. Graversen, 2001 Elastic Javadoc

Sumary

Comments

Help spread the word