first pass at docs, also adding a few validation checks in code