RDoc vs. alias_method

[Noah Easterly]

I'm working on a script that has to work across several versions of
ruby.
Sometimes, some versions don't have libraries that I require, so I get
around that by
having an alternate implementation for those versions.

For easy testing I like to be able to declare all the implementations
so I can run them in parallel, and compare results, and create aliases
to the 'best' implementation.

For example, if in 1.8.8, dentist.rb is available, and before that,
you could only get hygenist.rb, I might do something like this:

| class ToothCare
| dentist_load_error = nil
| begin
| require 'dentist'
| # gargle!
| def dentist_gargle
| #...
| end
| # rinse!
| def dentist_rinse
| #...
| end
| # spit!
| def dentist_spit
| #...
| end
| rescue LoadError => dentist_load_error
| end
| hygenist_load_error = nil
| begin
| require 'hygenist'
| # gargle!
| def hygenist_gargle
| #...
| end
| # rinse!
| def hygenist_rinse
| #...
| end
| # spit!
| def hygenist_spit
| #...
| end
| rescue LoadError => hygenist_load_error
| end
| prefix = if dentist_load_error.nil?
| 'dentist'
| elsif hygenist_load_error.nil?
| 'hygenist'
| else
| raise LoadError, [
| "Could not find dentist or hygenist, sorry...",
| dentist_load_error,
| hygenist_load_error
| ].join("\n")
| instance_methods.each do |method|
| next unless method =~ /^#{prefix}_(\w+)$/
| alias_method $1, method
| end
| end

Whoever uses ToothCare can just call #gargle,#rinse,or #spit - they
don't have to worry about which implementation they're using.
Meanwhile, I can use #dentist_gargle and #hygenist_gargle to test and
compare.

This works pretty well, except when I run RDoc. It's not smart enough
to figure out that the alias_method creates instance methods named
#gargle,#rinse, and #spit, and so they don't get documented.

Is there any easy and DRY way I can tell RDoc to document those
methods?

 

[Eric Hodel]

Whoever uses ToothCare can just call #gargle,#rinse,or #spit - they
don't have to worry about which implementation they're using.
Meanwhile, I can use #dentist_gargle and #hygenist_gargle to test and
compare.

This works pretty well, except when I run RDoc. It's not smart enough
to figure out that the alias_method creates instance methods named
#gargle,#rinse, and #spit, and so they don't get documented.

Is there any easy and DRY way I can tell RDoc to document those
methods?

Nope. The Ruby parser doesn't understand the document-method stuff
that the C parser has.

... So writing a patch and submitting it on the RDoc bug tracker is
the most DRY way to do that.

 

[Daniel DeLorme]

I'm working on a script that has to work across several versions of
ruby.
Sometimes, some versions don't have libraries that I require, so I get
around that by
having an alternate implementation for those versions.

For easy testing I like to be able to declare all the implementations
so I can run them in parallel, and compare results, and create aliases
to the 'best' implementation.

For example, if in 1.8.8, dentist.rb is available, and before that,
you could only get hygenist.rb, I might do something like this:

| class ToothCare
| dentist_load_error = nil
| begin
| require 'dentist'
| # gargle!
| def dentist_gargle
| #...
| end
| # rinse!
| def dentist_rinse
| #...
| end
| # spit!
| def dentist_spit
| #...
| end
| rescue LoadError => dentist_load_error
| end
| hygenist_load_error = nil
| begin
| require 'hygenist'
| # gargle!
| def hygenist_gargle
| #...
| end
| # rinse!
| def hygenist_rinse
| #...
| end
| # spit!
| def hygenist_spit
| #...
| end
| rescue LoadError => hygenist_load_error
| end
| prefix = if dentist_load_error.nil?
| 'dentist'
| elsif hygenist_load_error.nil?
| 'hygenist'
| else
| raise LoadError, [
| "Could not find dentist or hygenist, sorry...",
| dentist_load_error,
| hygenist_load_error
| ].join("\n")
| instance_methods.each do |method|
| next unless method =~ /^#{prefix}_(\w+)$/
| alias_method $1, method
| end
| end

Whoever uses ToothCare can just call #gargle,#rinse,or #spit - they
don't have to worry about which implementation they're using.
Meanwhile, I can use #dentist_gargle and #hygenist_gargle to test and
compare.

This works pretty well, except when I run RDoc. It's not smart enough
to figure out that the alias_method creates instance methods named
#gargle,#rinse, and #spit, and so they don't get documented.

Is there any easy and DRY way I can tell RDoc to document those
methods?

hmm, maybe you can split your code into mixins;

begin
require 'dentist'
module DentistToothCare
def dentist_gargle
#...
end
...
instance_methods.each do |method|
alias_method method, "dentist_#{method}"
end
end
rescue LoadError => dentist_load_error
end

class ToothCare
if dentist_load_error.nil?
include DentistToothCare
else
include HygenistToothCare
end
#doc for "gargle"
def gargle; super; end
end

Just a (dumb?) idea

Daniel

 

[Noah Easterly]

Nope. The Ruby parser doesn't understand the document-method stuff
that the C parser has.

.. So writing a patch and submitting it on the RDoc bug tracker is
the most DRY way to do that.

Thanks, all. As an immediate solution, I decided to make
DentistToothCare and HygenistToothCare sub-classes of ToothCare, and
overwrote ToothCare::new to return
one or the other, depending.

And if I get the time, I'll go for the longer term solution of
patching RDoc, since I use dynamic aliasing and code generation often
enough to make this an issue.