From: Gavin Sinclair <gsinclair@...>
Date: 2003-08-11T22:28:22+09:00
Subject: Re: Ruby docstrings

On Monday, August 11, 2003, 11:16:53 PM, Francis wrote:

> A related issue is that if you use method_missing to dispatch method
> calls, there's almost no standard way for a parser to figure out what
> sorts of methods you're intending to define. I run into this a lot
> because my pet project Lafcadio uses method_missing a lot to let
> objects serve as facades for collections of subsystems, and I just
> finished writing RDoc comments for everything. When it came down to
> the methods handled through method_missing, I had to write class
> comments because there's no individual method definition for RDoc to
> parse.

I imagine that this is the only kind of documentation that would make
sense in that scenario.

Classes that are documented "Supports all the methods of Foo::Bar, but
does *this* in addition" are well documented, IMO.

> All of this is not to complain about RDoc, which is a fantastic tool.
> In some ways, it's nice to have this sort of problem. For a language
> like Java you don't run into this problem because reflection is so
> bloody painful in that language. Ruby lets you be more flexible and
> clever with method names, but the downside of that is that it raises
> the bar for programs (like RDoc) whose functionality depends on
> understanding that code.


Gavin