documenting dynamic method with rdoc

[Patrick May]

Hello,

I have a class with this code:

# Append output to client
[ :<<, uts, :write, rint ].each{ |symbol|
define_method(symbol) { |*args|
@cgd.send_headers if (unbuffered?)
@content.send( symbol, args )
@output.send( symbol, args )
}
}

I can cause rdoc to document these methods with these stubs in the
source file before the above code:

# Append output to client
def << (*args) end
# Append output to client with line endings
def puts(*args) end
# Append output to client
def write(*args) end
# Append output to client
def print(*args) end

Is there another prefered way to document this sort of thing with rdoc?

Cheers,

Patrick

 

[Dave Thomas]

Is there another prefered way to document this sort of thing with rdoc?

I'm thinking about it at the moment. I'll probably add a way to
document classes and methods that are generated dynamically: I'm just
not sure how it should work yet.


Cheers

Dave

 

[Patrick May]

Hi,

I'm thinking about it at the moment. I'll probably add a way to
document classes and methods that are generated dynamically: I'm just
not sure how it should work yet.

My brief thoughts were:

+ 'true' dynamic documentation would require that rdoc execute your
application, and then pick a point at which to document the code.
Which seems problematic.

+ generated documentation is less valuable than composed
documentation, especially when describing how a system behaves at run
time. I thought it'd be simpler to tell rdoc "here's a method that
doesn't exist, but this is what I want to tell people it does". And
the stub methods seemed like a straight forward way of doing that.

I don't know what you are thinking about. My gut feeling was that it
might not be worth it, though I don't know much about rdoc.

Thanks for rdoc! I'm looking forward to Pickaxe 2.0 as well.

Cheers,

Patrick

 

[gabriele renzi]

Dave Thomas ha scritto:

on a side but related note: it would be nice if RDoc supported
documentation of classes generated via Class.new.
I quite usually write
SomeError=Class.new(Exception)

btw, I don't expect it to detect stuff like
a=Class
Foo=a.new

but 'grepping' only Class.new seem reasonable simple to me.