Skip to content
Advertisement

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

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?

Advertisement

Answer

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 contributions licensed under: CC BY-SA
8 People found this is helpful
Advertisement