Issue #19688 has been updated by nobu (Nobuyoshi Nakada). Description updated Status changed from Open to Feedback `#begin` has been parsed as a single line comment. Changing it can be incompatibility. Why not just indenting `=begin`? ---------------------------------------- Feature #19688: Add indentable block comment syntax https://bugs.ruby-lang.org/issues/19688#change-103270 * Author: ccmywish (Aoran Zeng) * Status: Feedback * Priority: Normal ---------------------------------------- Ruby's default block comment is using `=begin` and `=end` ```ruby =begin Some block comments =end ``` However, we must place them at the top of the line, thus we can't indent them, for example: ```ruby class A class B class C =begin The comment for this method =end def hello end end end end ``` This is something like the situation of `<<HEREDOC` and `<<-HEREDOC`. Finally, we added `<<~HEREDOC` which is very handy. Things become worse when documenting using `RDoc` and `YARD`, see the **686 lines** of the leading `#`, it's very trivial if we don't use block comment: https://github.com/ruby/net-http/blob/master/lib/net/http.rb#LL35C1-L721C1 So, I propose a new syntax to declare block comments using `#being` and `#end` ```ruby class A class B class C #begin The comment for this method @param str @return [String] Any other document. Now we are easy to break a line, without touching the leading `#` like before. #end def hello(str) end end end end ``` I've some thoughts on this: 1. Honestly, I don't know if `RDoc` and `YARD` rely on the line comment rather than block comment. 2. I choose `#begin` and `#end` because they still use the `#` symbol to denote that this is comment. 3. `#begin` and `#end`'s leading `#` doesn't conflict with the old `=begin` and `=end` for compatibility. 4. `#begin` may influence the speed of the lexer, because we now should scan at least later 5 characters after `#` -- https://bugs.ruby-lang.org/