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

24 May 2023

      Issue #19688 has been updated by austin (Austin Ziegler).

rubyFeedback (robert heiler) wrote in #note-3:
...
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.
`@param xyz` is not syntax for rdoc; it is something created by YARD out of some misbegotten love of Javadoc or Doxygen, I guess. I have nothing nice to say about that syntax, and several worse things to say about YARD's ignoring rdoc directives in favour of such silliness.

I think that the `=begin`/`=end` format has seen less use because I’m not entirely sure that rdoc supports parsing properly inside those comments, and it’s atypical to see `=begin`/`=end` comments attached to method definitions.

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

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