better return value documentation for promises