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?

CodePudding user response：

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; i.e. 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.)}

CodePudding user response：

I'm not sure if this answers your question, but this article (which happens to have an example with multiple @throws with the same exception, although it's not the topic of the article) suggests you shouldn't be documenting those exceptions at all, because they are unchecked and the documention would only repeat conditions of the @param tags.