rdoc and constructs like DL::Import's extern

[Ken Bloom]

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 ptsptr
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 ption
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 anic_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

 

[Logan Capaldo]

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

You could maybe make stubs for documentation purposes:

e.g. In some file parseoptions_doc.rb (that doesn't ever even get
included)

class ParseOptions
# This method frobinates the baz
def max_sentence_length(baz)
end

# this method somethings the whodinger
def cost_model_type
end
end

You just don't use this file in your actual code but when you run
rdoc over it, it should pick up the methods

 

[Ken Bloom]

You could maybe make stubs for documentation purposes:

e.g. In some file parseoptions_doc.rb (that doesn't ever even get
included)

class ParseOptions
# This method frobinates the baz
def max_sentence_length(baz)
end

# this method somethings the whodinger
def cost_model_type
end
end

You just don't use this file in your actual code but when you run
rdoc over it, it should pick up the methods

Then I still have to write all of the stubs. Although I suppose I
could make it automatically generated somehow.

--Ken Bloom