Documenting dynamic method with rdoc

ruby-talk
1

Hello,

I have a class with this code:

     # Append output to client
     [ :<<, :puts, :write, :print ].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

2

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

···

On Aug 29, 2004, at 1:48, Patrick May wrote:

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

3

Hi,

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.

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

···

On Sunday, August 29, 2004, at 07:20 AM, Dave Thomas wrote:

On Aug 29, 2004, at 1:48, Patrick May wrote:

4

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.