misc updates in code and inline documentation