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

user_2938364 0
Viewed 105

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?

throws code-documentation javadoc exception java
2 Answers

There is an Oracle style guide for javadocs:

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.

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

user_1399850

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.

user_3184930
Related