From: Ken Bloom <kbloom@...>
Date: 2006-07-13T07:40:13+09:00
Subject: rdoc and constructs like DL::Import's extern

I'm wrapping a C library (link-grammar, to be specific) in an
object-oriented ruby interface using DL::Import. The library is a very
well designed object-oriented C library, which is to say it uses very
consistent naming and calling conventions. Thus, the library lends
itself very well to automation when wrapping the the library in
object-oriented code.

I use DL::Import to create a CLib module containing all of the
functions in the C library. (Actually, I've wrapped extern in another
function which automatically defines certain things like safe string
handling where necessary, and automatic assignment of free functions)

In the various classes which call the functions in CLib, there was
also a lot to be gained by writing an extern-like function to automate
the work. For example, in the ParseOptions class,

class ParseOptions
   def initialize
      @optsptr=CLib.parse_options_create()
   end
   attr_reader :optsptr
   class <<self
   def option(*names)
      names.each do |name|
      class_eval <<-"end;"
	 def #{name}
	    CLib.parse_options_get_#{name}(@optsptr)
	 end
	 def #{name}=(val)
	    CLib.parse_options_set_#{name}(@optsptr,val.to_i)
	 end
      end;
      end
   end
   private :option
   end
   option :verbosity, :linkage_limit, :disjunct_cost
   option :min_null_count, :max_null_count, :null_block
   option :islands_ok, :short_length, :max_memory
   option :max_sentence_length, :max_parse_time
   option :cost_model_type, :screen_width, :allow_null
   option :display_walls, :all_short_connectors, :batch_mode
   option :panic_mode, :display_on, :display_postscript
   option :display_constituents, :display_bad, :display_links
   option :display_union, :echo_on
end

Is there any way to get rdoc to document all of the methods that the
option method automatically creates?

I have noticed that rdoc doesn't even know how to do it for the methods
created by DL::Import.extern. (I haven't worked with rails, but I
imagine rails has a similar problem.)

--Ken Bloom

-- 
I usually have a GPG digital signature included as an attachment.
See http://www.gnupg.org/ for info about these digital signatures.