Overridden methods in JavaDoc

Question

I'm documenting a Java program that I have developed, and wanted to know if JavaDoc will be generated for an inherited method (which is overridden) if I just document the superclass?

If I have a class called Vehicle with a drive() method in, and a sub-class called Car with the drive() method overridden, will the documentation for the Vehicles drive method be included in the Cars drive method if no Javadoc is put in the Car class?

Answer 1

[I] wanted to know if JavaDoc will be generated for an inherited method (which is overridden) if I just document the superclass?

Yes. If you don't have javadoc comments on a subclass, javadocs will be be generated based on the superclasses javadoc.

If you define javadocs in the subclass they will replace the inherited javadocs, but you can use {@inheritDoc} to include the respective superclass javadoc comments in the subclass javadocs.

Reference:

• https://docs.oracle.com/javase/6/docs/technotes/tools/solaris/javadoc.html#inheritingcomments

Answer 2

If you want to use the JavaDoc of the overridden method, use {@inheritDoc}. F. e. :

/**
  * {@inheritDoc}
  */
@Override
public double getX() { ... }

Please notice that almost every overriden method also inherits the upper docs :) . You can read about it in the oracle docs (thanks for the hint @Steve Kuo) .

The Javadoc tool has the ability to copy or "inherit" method comments in classes and interfaces under the following two circumstances. Constructors, fields and nested classes do not inherit doc comments... (1) Automatically inherit comment to fill in missing text ... (2) Explicitly inherit comment with {@inheritDoc} tag

Use @see if you want to reference to a similar/important/... method. Example of the java.awt.Point class:

 /**
 * Returns the location of this point.
 * This method is included for completeness, to parallel the
 * <code>getLocation</code> method of <code>Component</code>.
 * @return      a copy of this point, at the same location
 * @see         java.awt.Component#getLocation
 * @see         java.awt.Point#setLocation(java.awt.Point)
 * @see         java.awt.Point#setLocation(int, int)
 * @since       1.1
 */
public Point getLocation() { ... }