Add javadoc comments

Write javadoc comments for all the classes and interfaces.
Also include the public static methods.
Provide examples, sourced from the tests.
Link things nicely so that the currently hard-to-discover rule types are mentioned in a central place.