THE Java™ Programming Language, Fourth Edition

@throws IllegalArgumentException {@inheritDoc}

The onus is still on you to remember that unchecked exceptions must be manually documented in this way.

19.4. A Simple Example

The following is a version of the Attr class from page 76 with an example of javadoc comments:

/**

• An Attr object defines an attribute as a


• name/value pair, where the name is a String


• and the value an arbitrary Object.


• 
  


• @version 1.1


• @author Plato


• @since 1.0
  */
  public class Attr {
  /* The attribute name. /
  private final String name;
  /* The attribute value. /
  private Object value = null;

/**

• Creates a new attribute with the given name and an


• initial value of null.


• @see Attr#Attr(String,Object)
  */
  public Attr(String name) {
  this.name = name;
  }

/**

• Creates a new attribute with the given name and


• initial value.


• @see Attr#Attr(String)
  */
  public Attr(String name, Object value) {
  this.name = name;
  this.value = value;
  }

/* Returns this attribute's name. /
public String getName() {
return name;
}

/* Returns this attribute's value. /
public Object getValue() {
return value;
}

/**

• Sets the value of this attribute. Changes the


• value returned by calls to {@link #getValue}.


• @param newValue The new value for the attribute.


• @return The original value.


• @see #getValue()
  */
  public Object setValue(Object newValue) {
  Object oldVal = value;