[Rake-devel] Bug in rdoctask

[Gavin Sinclair]

Jim already said this wasn't a problem for him, but I thought I'd
flesh it out.

When I run an :rdoc task, it invariably fails (unless it's being done
for the _first_ time).  The reason?  In RDoc's words:

  Directory html already exists, but it looks like it
  isn't an RDoc directory. Because RDoc doesn't want to risk
  destroying any of your existing files, you'll need to
  specify a different output directory name (using the
  --op <dir> option).

When the :rdoc task is run, this is what happens:
 - rm_r @rdoc_dir rescue nil
 - build the command ("rdoc -o html .....")
 - run the command

The problem is the first step.  It empties the output directory, but
leaves hte directory itself there.  RDoc doesn't like putting
documentation into an empty directory, because it fears it is taking
up someone else's space.  It wants to create the directory itself, or
at least find a "created.rid" file there.

When I run :rerdoc, it works.  Why?  I don't know.  All that does is
run :clobber_rdoc first, and all *that* does is
  rm_r rdoc_dir rescue nil

The difference between them is @rdoc_dir vs rdoc_dir (instance
variable vs method).  Beats me.

Gavin