Official recommendation / coding style guide on using multiple @throws tags for the same exception in JavaDoc

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?

Herries

In my opinion it is not "just fine" but could be elegant? @throws SomeException enumerating many conditions, is noise, can be misunderstood as only one condition, and certainly makes the last conditions easy to miss, but having @throws SameException listed once and @throws SameException twice brings attention to unique conditions. I ended my first sentence with a question mark because I am like many others biased by our culture and habits. – Delwin

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

Davon

Answer 2

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.

Cartload

Well then, isn't it @param that repeats @throws? (not giving Oracle-recommended order any relevance). Even if "not null" would be repeated I don't see the problem with that. In fact, I would be confused if @param states "not null" but I see no NPE listed in the @throws clause; which one is right, which one is up-to-date? The argument that an exception should not be documented because it is unchecked I wholeheartedly disagree with. We document for humans, not machines. – Delwin