more validations added
cleaned up comments, started added doc links