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.
返回值注释会继承父类的返回值注释，在加上新的注释。
异常注释会继承父类的异常注释，在加上新的注释。