java子类继承父类方法、或者接口中方法的javadoc注释

说明

详情可以阅读：
https://docs.oracle.com/en/java/javase/19/docs/specs/javadoc/doc-comment-spec.html#method-comment-inheritance

• 子类继承父类、或者子类实现接口，在子类中为了避免重复写注释，可以在子类方法注释的主要描述部分、或者@return、@param、@throws标记后面的文本参数部分插入{@inheritDoc}标记，来明确继承javadoc注释。
  

• 注意：构造函数、属性、嵌套类不继承javadoc注释。

• 如果不写明确继承标记{@inheritDoc}，可能可以自动继承javadoc注释，也可能无法自动继承。

• 在子类的方法中，如果觉着有些javadoc注释不需要继承，而要写个性化的，那就在子类的方法javadoc注释中重写这部分，其它的照样继承。例如注释的主要描述部分重写了，而参数、返回部分继承，是可以的。总之，就是缺哪一部分继承哪一部分。

示例

javadoc的主要描述、参数、返回都加了{@inheritDoc}

定义一个接口：

package com.thb;

public interface Parent {

    /**
     * 返回姓名的全称.
     * @param firstName 名字
     * @param secondName 姓
     * @return 姓名的全称
     */
    String method(String firstName, String secondName);
}

定义一个子类实现接口：

package com.thb;

public class Child implements Parent {

    /**
     * {@inheritDoc}
     * @param   firstName  {@inheritDoc}
     * @param   secondName  {@inheritDoc}
     * @return  {@inheritDoc}
     */
    @Override
    public String method(String firstName, String secondName) {
        return firstName + secondName;
    }
}

运行javadoc命令生成帮助文档：

打开生成的帮助文档，看看内容：

JDK的代码样例：BufferedReader

package java.io.BufferedReader中的read函数：

/**
 * Reads characters into a portion of an array.
 *
 * <p> This method implements the general contract of the corresponding
 * {@link Reader#read(char[], int, int) read} method of the
 * {@link Reader} class.  As an additional convenience, it
 * attempts to read as many characters as possible by repeatedly invoking
 * the {@code read} method of the underlying stream.  This iterated
 * {@code read} continues until one of the following conditions becomes
 * true:
 * <ul>
 *
 *   <li> The specified number of characters have been read,
 *
 *   <li> The {@code read} method of the underlying stream returns
 *   {@code -1}, indicating end-of-file, or
 *
 *   <li> The {@code ready} method of the underlying stream
 *   returns {@code false}, indicating that further input requests
 *   would block.
 *
 * </ul>
 * If the first {@code read} on the underlying stream returns
 * {@code -1} to indicate end-of-file then this method returns
 * {@code -1}.  Otherwise this method returns the number of characters
 * actually read.
 *
 * <p> Subclasses of this class are encouraged, but not required, to
 * attempt to read as many characters as possible in the same fashion.
 *
 * <p> Ordinarily this method takes characters from this stream's character
 * buffer, filling it from the underlying stream as necessary.  If,
 * however, the buffer is empty, the mark is not valid, and the requested
 * length is at least as large as the buffer, then this method will read
 * characters directly from the underlying stream into the given array.
 * Thus redundant {@code BufferedReader}s will not copy data
 * unnecessarily.
 *
 * @param      cbuf  {@inheritDoc}
 * @param      off   {@inheritDoc}
 * @param      len   {@inheritDoc}
 *
 * @return     {@inheritDoc}
 *
 * @throws     IndexOutOfBoundsException {@inheritDoc}
 * @throws     IOException  {@inheritDoc}
 */
public int read(char[] cbuf, int off, int len) throws IOException {
    Object lock = this.lock;
    if (lock instanceof InternalLock locker) {
        locker.lock();
        try {
            return implRead(cbuf, off, len);
        } finally {
            locker.unlock();
        }
    } else {
        synchronized (lock) {
            return implRead(cbuf, off, len);
        }
    }
}

JDK的代码样例：FileInputStream中的覆盖函数transferTo

/**
 * {@inheritDoc}
 */
@Override
public long transferTo(OutputStream out) throws IOException {
    long transferred = 0L;
    if (out instanceof FileOutputStream fos) {
        FileChannel fc = getChannel();
        long pos = fc.position();
        transferred = fc.transferTo(pos, Long.MAX_VALUE, fos.getChannel());
        long newPos = pos + transferred;
        fc.position(newPos);
        if (newPos >= fc.size()) {
            return transferred;
        }
    }
    return transferred + super.transferTo(out);
}