From: Alex Chaffee <alexch@...>
Date: 2011-08-09T04:13:54+09:00
Subject: Re: Brainstorming ideas how to improve Ruby's documentation

> By default RDoc hyperlinks things that look like methods, words like foo_bar.  I think it's still occasionally overzealous when you have commonly-named classes but I'm unsure how to make it less eager yet.
>

Yeah, it's a sticky problem, I admit. In general I'd say to err on the
side of being conservative, though I'm not quite sure what that means
in practice.

One example is that, at least before, class names inside code blocks
were enlinkenated. That seems to have stopped recently; not sure if
it's rdoc or darkfish or what that corrected it.

>> it has unmemorable and randomly changing anchor link
>> names,
>
> This no longer happens.  Example:
>
> http://docs.seattlerb.org/minitest/MiniTest/Assertions.html#method-i-assert_empty

Yay!

>> it often links to a page describing a *file* instead of the
>> documented *class* inside that file
>
> Please show me an example, this shouldn't happen unless you have .rb or .txt on the end.

With darkfish, the first thing the user sees on the left side is a
list of file names. Clicking on those gives a page (actually I think
it's a lightbox, but same diff) with no info and no links to the
classes/modules defined inside that file.

e.g. from http://erector.rubyforge.org/rdoc/Erector.html click on
"abstract_widget.rb". You see a big bunch o' nothin', not even a link
to http://erector.rubyforge.org/rdoc/Erector/AbstractWidget.html which
is what you wanted/expected when you clicked on "abstract_widget".

>> For command-line docs, ri works pretty well, but the ri db is not
>> installed by rvm (‼!)
>
> Run rvm docs generate

Yeah, I know, but most people don't do this step (see ADHD note).

> We're working on improving this some in RubyGems 1.9 and forward, but that effort has been stalled while we fix bugs for Ruby 1.9.3.
>

Keep up the good work!

 - A

-- 

Alex Chaffee - alex@cohuman.com - http://alexch.github.com
Stalk me: http://friendfeed.com/alexch | http://twitter.com/alexch |
http://alexch.tumblr.com