Line with "#--" not working according to documentation.

[cfbrobak]

So far we have been using the RDoc version included in the Standard Library for Ruby version 1.8.7. That is RDoc version 1.0.1.

Our coding style specifies method comments formatted like this:

#---------------------------------------------------------------------
#++
# <method description>
#---------------------------------------------------------------------
def foobar()
  ...
end

We have chosen this style as the "#---..." lines nicely highlight a comment for someone looking at the source code. This is obviously a matter of taste.

The line starting with "#--" and all following lines up to and including the line starting with "#++" are discarded by RDoc while generating HTML. In this case there are no lines in between start and stop.

Well, we have now been trying RDoc version 3.3, and a line starting with "#--" no longer turns off RDoc generation. That is, unless the line contains only "#--" followed by a newline. If "#--" is followed by any other character, it does not work.

The RDoc 3.3 documentation says:

"RDoc stops processing comments if it finds a comment line starting with -- right after the # character (otherwise, it will be treated as a rule if it has three dashes or more). This can be used to separate external from internal comments, or to stop a comment being associated with a method, class, or module. Commenting can be turned back on with a line that starts with ++."

I have managed to get it to work by modifying the regular expressions in method "remove_private_comments" in file "lib/rdoc/parser/ruby.rb":

##
# Removes private comments from +comment+

def remove_private_comments(comment)
  comment.gsub!(/^#--.*\n(.*\n)*?^#\+\+.*\n?/, '')
  comment.sub!(/^#--.*/m, '')
end 

I believe this now works as documented. You may be able to improve on my regular expressions as I am far from an expert.

Best regards,

Claus Folke Brobak
JN Data, Denmark

[drbrain]

I chose a slightly less strict version of your regexp as the m flag is set. This should fix your documentation: @9a97f628

Please reopen if it does not.