improving documentation and fixing some clients