java1.5中{@inheritDoc}的使用

java1.5中@Override还不能用在interface上，只能用在class上。给我们的代码注释带来了一定的烦恼。 
为了表明一个方法是实现一个interface，我们可以使用{@inheritDoc}来标识，同时，该tag会把super type的注释复制下来。 

public interface A {
    /**
     * F method.
     * @param a para a.
     * @param b para b.
     * @return f(a,b).
     * */
    public int f(int a, int b);
}
class B implements A {
    /**
     * {@inheritDoc}
     * */
    public int f(int a, int b) {
        return 0;
    }
}

在生成的html中，我们可以看到B的方法注释完全复制自A. 

public int f(int a,int b)

F method.

Specified by:
f in interface A
Parameters:
a - para a.
b - para b.
Returns:
f(a,b).

当然，我们有可能改变接口的约定（不推荐这么做），这时，可以只注释改变的注释元素。 

/**
 * {@inheritDoc}
 * F method, compute sum.
 * @param a a>=0
 * @return a+b
 * */
public int f(int a, int b) {
    return 0;
}

这个的javadoc的结果为 

f
public int f(int a,int b)

F method. F method, compute sum.

Specified by:
f in interface A
Parameters:
a - a>=0
b - para b.
Returns:
a+b

可以看到，方法的主体注释文本为两个主体注释的拼接，参数，返回值都可以覆盖掉接口的注释。 

对于异常的注释的继承比较特殊： 
若子类没有声明父类的异常，则父类的异常注释不会被继承。 
子类只会继承它和父类共同声明的异常。 
当然，异常的注释，子类可以覆盖掉父类的注释。 

推荐的异常注释是子类列出所有的异常，如果父类也声明了该异常，则用 
@throws IOException {@inheritDoc} 
继承该异常的注释。 

所有的注释继承都有拼接功能，如 
* @return {@inheritDoc} a+b. 
* @throws IOException {@inheritDoc} when file is missed. 
返回值注释会继承父类的返回值注释，在加上新的注释。 
异常注释会继承父类的异常注释，在加上新的注释。