various lint fixes, some explanatory documentation.