documented new functions