add more doxygen comments. refine some internal method names