Improving docs about severity
Some javadoc improvements