I'm reading J. Bloch's effective Java and now I'm at the section about documenting unchecked exceptions. He said that
Use the Javadoc @throws tag to document each unchecked exception that a method can throw [...].
public interface Parameters {
//other method ommited
/**
* __DESCRIPTION_OMMITED__
*
* @throws ParameterAlreadyExistsException If a parameter with the same name already exists in this container.
*/
public <M> void put(ParameterMetaData<M> p, M value);
}
where public interface ParameterMetaData<ValueType>{ } is just a marker to ensure compile-time type-safety. ParameterAlreadyExistsException is a direct subclass of RuntimeException .
Here is a base implemetation of it:
public final class ParametersImpl implements Parameters{
private final Map<ParameterMetaData<?>, Object> parameters;
@Override
public <M> void put(ParameterMetaData<M> p, M value){
if(value == null)
return;
if(parameters.containsKey(p))
throw new ParamAlreadyExistsException(String.format("The parameter with the name %s already exists. Value: %s", p.getClass(), parameters.get(p)));
try{
parameters.put(p, value);
} catch (Exception e){
throw new RuntimeException(String.format("Parameter insertion failed. ParameterMetaData: %s Value: %s", p.getName(), value), e);
// ^----------------Here non-documented exception is thrown.
}
}
//remainders ommited
}
Since the Map#put(K, V) method throws and my implementaiton uses it and throws RuntimeException if somehting went wrong, how should I document that fact? And should I ever do this? Currently it may hard to say anything judging by the interface documentation why the RuntimeException is thrown.
QUESTION: How should I deal with implementation specific exceptions? should I document them?
