tweak and add documentation comments