Feature #19688: Add indentable block comment syntax

• Status: Closed
• Assignee: -
• Target version: -

[ccmywish (Aoran Zeng)]

Ruby's default block comment is using =begin and =end

=begin
  Some block comments
=end

However, we must place them at the top of the line, thus we can't indent them, for example:

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

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 #

[nobu (Nobuyoshi Nakada)]

• Description updated (diff)
• 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?

[nobu (Nobuyoshi Nakada)]

• Related to Feature #13518: Indented multiline comments added

[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.

[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.

[matz (Yukihiro Matsumoto)]

• Status changed from Feedback to Closed

I can understand the need for multi-line comment (although I mostly use Emacs or IDE to comment a region out).
But proposed #begin and #end is not acceptable, due to the compatibility issue @nobu (Nobuyoshi Nakada) mentioned.

Matz.