added more documentation and notes