clean up and extend header docs (@throws, @return)