many small improvements to inline documentation