在Javadoc中使用多少@throws

Question

我应该如何@throws在我的javadoc或任何API中使用？例如,如果我有:

LDAPException
NullPointerException
IllegalArgumentException
Exception

我应该@throws为每个人使用,还是应该说@throws Exception？

Answer 1

理想情况下,javadoc @throws子句应该是实际方法throws子句的超集.

例如,如果您的方法throws IOException,您不仅可以@throws IOException解释发生通用I/O错误的情况,还可以@throws FileNotFoundException(一个子类IOException)来讨论可能发生的原因.

同样,@throws NullPointerException即使您没有声明,也可以记录状态,即使您没有声明throws NullPointerException,因为它是未经检查的异常,并且不需要(通常也不是)写入方法签名.

你@throws Exception呢？不,但是,更一般地说,你不应该throws Exception.这是一个不同的讨论.但结果是,不,在javadoc中重复这种不良做法并不好.它会谈到什么 - 可能发生的不同异常？然后为什么不一个一个一个地记录它们@throws呢？