From: "austin (Austin Ziegler) via ruby-core" <ruby-core@...>
Date: 2023-05-24T19:59:22+00:00
Subject: [ruby-core:113642] [Ruby master Feature#19688] Add indentable block comment syntax

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/

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