From: "ccmywish (Aoran Zeng) via ruby-core" <ruby-core@...>
Date: 2023-05-24T10:47:41+00:00
Subject: [ruby-core:113621] [Ruby master Feature#19688] Add indentable block comment syntax

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/
 ______________________________________________
 ruby-core mailing list -- ruby-core@ml.ruby-lang.org
 To unsubscribe send an email to ruby-core-leave@ml.ruby-lang.org
 ruby-core info -- https://ml.ruby-lang.org/mailman3/postorius/lists/ruby-core.ml.ruby-lang.org/