[Bug] rdoc doesn't detect heredoc comments

[NlightNFotis]

Hello.

I'm going through the book 'Ruby By Example' by Kevin C. Baird, and I have a small code example for the 99 bottles problem:

#!/usr/bin/env ruby
# 99bottles.rb

class Wall
  def initialize(num_of_bottles)
    @bottles = num_of_bottles
  end

=begin rdoc
Predicate, ends in a question mark, returns <b>Boolean</b>.
=end
  def empty?()
    @bottles.zero?
  end

  def sing_one_verse!()
    puts sing(' on the wall, ') + sing("\n") + take_one_down! + sing(" on the wall.\n\n")
  end

  private

  def sing(extra='')
    "#{(@bottles > 0) ? @bottles : 'no more'} #{(@bottles ==  1) ? 'bottle' : 'bottles'} of beer" + extra
  end

=begin rdoc
Destructive method named with a bang because it decrements @bottles.
Returns a <b>String</b>.
=end
  def take_one_down!()
    @bottles -= 1
    'take one down, pass it around, '
  end
end


wall = Wall.new 99
puts wall.sing_one_verse!
puts wall.sing_one_verse!

wall = Wall.new 1
puts wall.sing_one_verse!

I know that the book is fairly old, and that maybe the exact output shouldn't be trusted, but I'm running this through rdoc and I get the following:

$ rdoc -C 99bottles.rb
Parsing sources...
100% [ 1/ 1]  99bottles.rb

The following items are not documented:

In files:
* 99bottles.rb

  class Wall

    # in file 99bottles.rb:4
    def self.new(num_of_bottles); end

    # in file 99bottles.rb:15
    def sing_one_verse!(); end

  end



  Files:      1

  Classes:    1 (1 undocumented)
  Modules:    0 (0 undocumented)
  Constants:  0 (0 undocumented)
  Attributes: 0 (0 undocumented)
  Methods:    3 (2 undocumented)

  Total:      4 (3 undocumented)
   25.00% documented

  Elapsed: 0.0s

It appears that rdoc cannot detect the documentation of the Wall#take_one_down! method, which is based on a heredoc. I don't know if that's to be expected or not (say, if the functionality got removed in the past and I'm unaware), but it seems like a problem that the documentation of Wall#empty? works based on the exact same form. I am using rdoc 6.5.0 and ruby 3.1.3p185 (2022-11-24 revision 1a6b16756e) [arm64-darwin21]

[NlightNFotis]

Okay, ignore me - I just realised it's not an issue. It works fine, but reporting is slightly ambiguous.

The method doesn't appear documented because it is marked private. I need to add a comment #:doc: next to its definition, and then rdoc works fine with it.

Closing as it's no longer relevant.