document new call semantics