improved api comments on deferral