documented new interface