fixup documentation per @lsegal's feedback
make default return void, as we dont tend to indicate return when its not useful
restore `@param name [Type]` format and switch @attr to match
fixup a warning
[skip ci]
Merge pull request #1389 from rspec/documentation_tweaks

Documentation tweaks