Ruby

Feature #19688

Updated by nobu (Nobuyoshi Nakada) over 2 years ago

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 `#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 `#`

Back