[ruby-core:113621] [Ruby master Feature#19688] Add indentable block comment syntax

24 May 2023

      Issue #19688 has been reported by ccmywish (Aoran Zeng).

----------------------------------------
Feature #19688: Add indentable block comment syntax
https://bugs.ruby-lang.org/issues/19688

* Author: ccmywish (Aoran Zeng)
* Status: Open
* 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/