Changing code will break existing users -- changing the doc to match the code seems safer.