added documentation, consistency and sane defaults