inline documentation & some code improvements