关于在 JavaDoc 中对同一异常使用多个 @throws 标签的官方推荐/编码风格指南

Question

I just recently found out that one can use multiple @throws tags for the same exception in Javadoc .

One of my students used it to document one of his methods in Connect Four :

/*
 * ...
 * @throws IllegalArgumentException if the number of rows or columns is invalid 
 * @throws IllegalArgumentException if one of the players has {@link Stone#None} as stone
 * @throws IllegalStateException if both players use the same stone color
 */
public void doSomething(...) { ... }

Now my (and his) question: Is there an official style guide or a general recommendation on whether to use a single @throws tag or "is it fine" to use multiple ones per exception type?

Answer 1

There is an Oracle style guide for javadocs:

• How to Write Doc Comments for the Javadoc Tool .

Whether that counts as "official" depends on your point of view. Either way, I cannot see any mention in that document of multiple tags for the same exception.

However, according to the following Q&A, multiple @throws tags for the same exception is supported by the standard Javadoc tool chain; ie each of them will result in an entry in the generated HTML.

• Can I use multiple @throws tags for the same exception in Javadoc?

_{(My personal opinion is the javadocs will be more readable if you don't do this, but that is just my opinion .)}

Answer 2

我不确定这是否能回答您的问题，但这篇文章（恰好有一个带有多个@throws的示例，但具有相同的异常，尽管这不是文章的主题）建议您根本不应该记录这些异常，因为它们未选中，并且文档只会重复@param标记的条件。