include comments and recent changes to docs