Java Minutiae - @return

Often I see Javadoc with only an @return tag:

  /**
   * @return the current user assigned to make the delivery, or {@code null} 
   *      if no such assignment has been made.
   */
  public User getDeliveryPerson();

Unfortunately, the javadoc command line tool doesn't handle this format particularly well. Since the method has no summary, nothing is listed in the Javadoc overview:

Instead, whenever your method has no description, promote the @return tag into the method description by replacing @return with the word "Returns":

  /**
   * Returns the current user assigned to make the delivery, or {@code null} 
   * if no such assignment has been made.
   */
  public User getDeliveryPerson();

This makes the Javadoc report much better:

Thanks to Kevinb for the tip.

# posted by Jesse Wilson on Friday, February 29, 2008