Adding appledoc comments which led to some small code refinements.
Added Xcode target to generate documentation.
Increased robustness of tests and fixed bugs exposed by the better
tests.
Updated documentation to include possible kinds of errors returned when
parsing command-line options.