1

How can I get rdoc to display line numbers? I know there is -N switch, however even with it I get just

# File config.rb, line 40
def port
  @conf[:port].to_a || DEFAULT_PORT
end

I would like to have line number before each line, is that even possible?

graywolf
  • 7,092
  • 7
  • 53
  • 77

1 Answers1

1

UPDATE

It's a bug - thanks to your question, it has been fixed in Rdoc 6.1.0.

If your rdoc --version is older than that, update it with gem install rdoc -v 6.1, or simply gem install rdoc to get the latest version. Alternatively, update/specify rdoc version in Gemfile if you use Bundler.

After the fix, -N option properly enables numbering for each line:

# File config.rb
40 def port
41   @conf[:port].to_a || DEFAULT_PORT
42 end

Original answer below:

Looks like it is currently possible only through a hack in RDoc source code. From rdoc --help :

-N, --[no-]line-numbers

Include line numbers in the source code. By default, only the number of the first line is displayed, in a leading comment.

Initially, I misunderstood and thought that inserting number of first line is the default, minimalistic behaviour for this option, that can be modified in some other way - like customizing in templates. Eventually I realized that --no-line-numbers does nothing :) So yes, it's clearly a bug.

In RDoc code, the method responsible for inserting line numbers can be found in markup generator. Unfortunately, as of version 6.0.1, it doesn't seem to be used at all. Quick fix to enable it manually:

  1. Find location of RDoc source with gem which rdoc and cd to that directory
  2. Edit generator/markup.rb - find @add_line_numbers variable and set it to true (line 68 in github source I linked)
  3. Run rdoc again, lines in your source fragments should be numbered properly.

That's of course far from proper bugfix. As an exercise, I also tried to fix it with monkey-patch and then run RDoc through a Rake task. I eventually gave up when I realized that RDoc::Task doesn't even accept -N as an option :(

As a footnote - YARD does proper line numbering and it's enabled by default.

Community
  • 1
  • 1
Bartosz Pietraszko
  • 1,367
  • 9
  • 9
  • So if I understand correctly it's not possible without hacking on rdoc's source and if I want it to just respect `-N` I should make feature request towards rdoc's tracker? ; ps: I'm using the standard generator to html (I think that's darkfish?) ; ps2: I'm fairly new to rdoc (I don't usually comment my code) so my understanding of what "generator" is might be off – graywolf Feb 07 '18 at 00:15
  • That's the only solution I have found so far. More proper way would me probably running rdoc through a Rake task and altering that variable from within task. I will edit my answer once I figure it out. – Bartosz Pietraszko Feb 07 '18 at 07:41
  • 1
    I reported the issue and apparently bugfix is under way https://github.com/ruby/rdoc/pull/630 . I will edit my answer when fixed version is officially released. – Bartosz Pietraszko Jun 25 '18 at 20:30
  • I see your's PR is merged to ruby master, i see it available in ruby 2.6.2 – zw963 Mar 29 '19 at 08:55
  • @zw963 PR wasn't mine, only the issue but thanks - I updated my answer. – Bartosz Pietraszko Mar 29 '19 at 14:53