From: Eric Hodel <drbrain@...7.net>
Date: 2011-08-09T03:25:50+09:00
Subject: Re: Brainstorming ideas how to improve Ruby's documentation

On Aug 7, 2011, at 2:42 PM, Alex Chaffee wrote:
> […]
> However, they don't fix some of the core problems of rdoc. Even
> without frames (darkfish ftw!) rdoc makes too many words hyperlinks to
> the wrong pages,

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.

> 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

> 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.

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

Run rvm docs generate

> and many people ritually install gems with
> --no-ri --no-rdoc because generating the documentation often makes the
> install take 3x as long (and the whole world has ADHD these days so 3x
> is unacceptable).
> 
> (By the way, would it be so horrible if "gem install" forked off a
> process to build the docs in the background? On systems that support
> fork, of course.)

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.