improved validation, added documentation