Should unchecked Exception be described in JavaDoc?

Question

I have the following code:

public User getUserById(Long id) {
checkUserExists(id);
return repo.findOne(id);
}

private void checkUserExists(Long id) {
    if (id == null || !repo.exists(id)) {
        throw new NoUserFoundException("No User exists with id: " +id);
    }
}

According to Oracle:

"Unchecked exceptions do not need to be declared in a method or constructor's throws clause if they can be thrown by the execution of the method or constructor and propagate outside the method or constructor boundary."

Do I have to describe the exception anyway in the JavaDoc (Without the @throws clause, but only describe?) What is the best way to describe such an unchecked exception in JavaDoc?

Answer 1

You are writing Javadoc for the user of your method. If it's useful for that user to know that it may throw an exception, document it!

In your case, it seems that it is indeed useful for the user to know that a NoUserFoundException is thrown if the user is not found.

In other cases it's less useful. For example, in many cases the fact that a NullPointerException is thrown if a parameter is null is not documented in the Javadoc because it's often somehow implied that a parameter cannot be null.

By the way, Oracle is talking about the throws class appearing after the method declaration, not about the Javadoc. If you decide to document a non-checked exception, it makes sense to use the @throws clause.