From: "nobu (Nobuyoshi Nakada) via ruby-core" <ruby-core@...>
Date: 2023-05-24T14:19:37+00:00
Subject: [ruby-core:113629] [Ruby master Feature#19688] Add indentable block comment syntax

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/
 ______________________________________________
 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/