javadoc + remove Availability|up because it's duplicated + improve
documentation