closes #264, clarified/extended documentation