Feature #19688
Updated by nobu (Nobuyoshi Nakada) 12 months ago
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 `#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 `#`