Feature #19688
closedAdd indentable block comment syntax
Description
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:
- Honestly, I don't know if
RDoc
andYARD
rely on the line comment rather than block comment. - I choose
#begin
and#end
because they still use the#
symbol to denote that this is comment. -
#begin
and#end
's leading#
doesn't conflict with the old=begin
and=end
for compatibility. -
#begin
may influence the speed of the lexer, because we now should scan at least later 5 characters after#
Updated by nobu (Nobuyoshi Nakada) over 1 year ago
- 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
?
Updated by nobu (Nobuyoshi Nakada) over 1 year ago
- Related to Feature #13518: Indented multiline comments added
Updated by rubyFeedback (robert heiler) over 1 year ago
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.
Updated by austin (Austin Ziegler) over 1 year ago
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.
Updated by matz (Yukihiro Matsumoto) over 1 year ago
- 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.