javadocs for new state