method - javadoc best practices

En javadoc, ¿cuál es la diferencia entre las etiquetas @throws y @exception?

Question

Tome la siguiente implementación de una pila de caracteres basada en matrices, por ejemplo:

public char peek() throws Underflow {
    if (!isEmpty()) {
        return stack[pos];
    } else {
        throw new Underflow("Peeking at an empty stack.");
    }
}

Cuando uso solo un editor de texto, siempre uso la etiqueta @exception, pero ahora mi IDE (Netbeans) usó @throws al generar el javadoc.

Entonces, mi pregunta es, ¿cuál es la diferencia entre los dos y cuándo debería preferirse uno sobre otro (utilizando el código anterior, por ejemplo)?

Answer 1

No hay ninguno, son sinónimos. De la documentación :

Documentar excepciones con la etiqueta @throws
NOTA - Las etiquetas @exception y @exception son sinónimos.

Answer 2

Se agregó @throws porque es una palabra clave (cláusula de "arroja" en una declaración de método),

y, como verbo, es más natural leer. Esto se lee como una oración:

@throws NullPointerException

Si bien esto parece más redundante:

@exception NullPointerException

De lo contrario, ambos son sinónimos.

Answer 3

@exception no es 100% correcta si el código lanza un Throwable . @throws es más exacto. (Me doy cuenta de que no hay un buen caso de uso para usar throw new Throwable() , pero en teoría está permitido).