rdoc

[rubocop]

rdoc

[bbatsov]

Will do :-)

I'd not dictate rdoc here, as YARD is sooo much nicer…

[dacat]

I like YARD as well, but I'd go with rdoc since it's in ruby-core and YARD requires an additional dependency.

[bambery]

The guide says not to leave an "empty line" between the comment block and the def, but a newline is standard per rspec documentation.

http://docs.seattlerb.org/rdoc/#label-Writing+Documentation

[bbatsov]

Seems like there's little interest in this so I'll be closing the ticket. Let's give the people the freedom to pick whatever doc engine they want (these days I use only yard).

[philoserf]

While the rdoc/yard comment debate may not be resolved, I believe some style guidance on such documentation should be included.

See also: http://robots.thoughtbot.com/letting-your-code-speak-for-itself