all good points. I have cleaned up the documentation in 6665a2b