beefed up the documentation a little for #1