fixing up gem build warnings
adding some docos to the code