RDoc vs. alias_method

Discussion in 'Ruby' started by Noah Easterly, Aug 10, 2007.

  1. 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?
    Noah Easterly, Aug 10, 2007
    #1
    1. Advertising

  2. Noah Easterly

    Eric Hodel Guest

    On Aug 10, 2007, at 08:16, Noah Easterly wrote:
    > 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.

    --
    Poor workers blame their tools. Good workers build better tools. The
    best workers get their tools to do the work for them. -- Syndicate Wars
    Eric Hodel, Aug 11, 2007
    #2
    1. Advertising

  3. Noah Easterly wrote:
    > 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
    Daniel DeLorme, Aug 11, 2007
    #3
  4. On Aug 10, 9:14 pm, Eric Hodel <> wrote:
    > On Aug 10, 2007, at 08:16, Noah Easterly wrote:
    >
    > > 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.
    >
    > --
    > Poor workers blame their tools. Good workers build better tools. The
    > best workers get their tools to do the work for them. -- Syndicate Wars


    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.
    Noah Easterly, Aug 13, 2007
    #4
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Andreas Schwarz
    Replies:
    6
    Views:
    241
    Randy W. Sims
    Jan 1, 2004
  2. Brian Schröder
    Replies:
    5
    Views:
    128
    Dave Thomas
    Sep 18, 2004
  3. Daniel Berger
    Replies:
    1
    Views:
    138
    Dave Thomas
    Nov 2, 2004
  4. Iwan van der Kleyn

    rdoc: how to add readme.rdoc as index.html?

    Iwan van der Kleyn, Apr 26, 2005, in forum: Ruby
    Replies:
    1
    Views:
    218
    Stefan Lang
    Apr 26, 2005
  5. Paul Van Delst

    How to use rdoc parsers outside of rdoc?

    Paul Van Delst, Jul 27, 2006, in forum: Ruby
    Replies:
    0
    Views:
    95
    Paul Van Delst
    Jul 27, 2006
Loading...

Share This Page