Javadoc improvements

Adding marble diagrams, making the javadocs more consistent in their terminology & formatting.