Name: rmT116609 Date: 09/25/2003


A DESCRIPTION OF THE REQUEST :
JavaDoc should support a new tag called @super. This tag, when included in the JavaDoc for a class or method would automatically insert the documentation from any inherited class or method.


JUSTIFICATION :
Dave Thomas and Andy Hunt's "DRY" principle ("Don't Repeat Yourself") applies to documentation as well as code. Just as you don't want to have multiple copies of the same code running around, re-writing documentation for a class who's behavior is the same as its parent is wasteful and dangerous.

It would be nice to be able to document behavior at the highest level of abstraction, and simply add a @super tag to the doc for any subclasses. That way, the documentation is written in only one place, but all the relevant classes get a copy when the JavaDoc is built.

This would greatly cut down on the amount of documentation that Java developers need to write. Only additions to behavior would need to be documented. It would also decrease inconsistancies because the documentation for a class/method would always be in one and only one place.


---------- BEGIN SOURCE ----------
// An example of this tag in use...

/**
 * Stores information about the user of the system
 *
 * @author Ben Rady
 * @see LoginBean
 */
public interface UserInfo
{
  /**
   * Returns the User ID. This String cannot be more than 8 charecters long.
   *
   * @return a UserID String
   */
  public String getUserID();

  /**
   * Returns a string representation of the password.
   *
   * @return user password
   */
  public String getPassword();
}

// and now, the implementation...

/**
 * @super
 */
public class MD5EncodedUserInfo implements UserInfo
{
  /**
   * @super
   */
  public String getUserID()
  {
    ...
  }

  /**
   * @super
   *
   * The password returned is an MD5 encoded version of the cleartext password.
   */
  public String getPassword()
  {
    ...
  }
}
---------- END SOURCE ----------
(Incident Review ID: 208952)
======================================================================