Javadoc improements

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