From: sera@... (Francis Hwang)
Date: 2003-08-12T01:59:23+09:00
Subject: Ruby docstrings

Gavin Sinclair <gsinclair@soyabean.com.au> wrote in message news:<977617383.20030811232553@soyabean.com.au>...
> 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.

I suppose it depends on who you're writing the documentation for. In
the example I'm thinking of there's an object facade (called the
ObjectStore) which abstracts away a lot of its functionality to
subsystems -- part of the reason there's so much dispatching to
suybsystems is so that clients don't have to think about where the
functionality lives. For them I'd like to pretend that all the methods
belong to the facade.

For people who want a deeper look into the design, you want more
explicit mention of what subsystem handles what methods. Though now
that I think about it I suppose a format like RDoc lends itself more
to deep detail than overviews -- I should probably just write more
how-to type documents for that stuff, hm?

Francis