added some extra validation, documentation