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

24 May 2023

      Issue #19688 has been updated by rubyFeedback (robert heiler).

I think I can somewhat understand the rationale for the issue, even
though I personally don't really need it. I use mostly HEREDOC syntax,
in particular:

    result = <<-EOF

      This is a heredoc.

      It provides a nice syntax
      for multiline strings

    EOF
    return result

So I typically just capture it into a variable, and if necessary
I then modify the variable before returning or displaying it
on the commandline. I also stopped using =begin/=end a long time
ago and just comment with '#' instead. This may be a bit more cumbersome
to do when one uses a simple editor, but I found that it is also
easier to understand and ultimately quicker in the long run. Although
I have no data to back this up, I think most ruby users tend to use
'#' and HEREDOC; =begin/=end is, I think, not as popular. Perhaps by
being more flexible it could become more popular, but I am
not certain. I think ruby user may not be that fond of the
=begin/=end variant.

As for rdoc: I don't like rdoc's syntax either. I feel the
entries such as "@param xyz" are quite distracting. These
are, however had, extremely popular - a lot of ruby gems
use them, probably because the generated documentation e. g.
in yard, can be quite helpful.

PS: If tenderlove reads this, it reminds me a bit of his 
old blog entry "I am a puts debugger", with which I agree
with. Simplicity is kind of neat. I guess a question here
may be how long-term ruby developers out there comment 
their source code. =begin/=end is probably quite rare.

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

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