doc improvements #4
Description
Every package should have a package comment providing documentation, with attention paid to the short text in the top-level package's sub-package links.
The top-level README should include a worked example.
Should probably have executable examples for testing.
What else?