added documentation, removed code inconsistencies