javadoc changes

added marble diagrams, standardized terminology and formatting