Pretty sure we have _many_ methods where `@return` comes after `@param`, so if that never works it seems better to fix the docs-generator bug than reorder all our comments in a nonstandard way...

Does moving the "A promise that..." part onto the same line as `@return` fix it?  I wonder if the issue is just that the initial line is blank.