Clarify promise usage with  in docs to cover bug 835536