From: Gavin Sinclair <gsinclair@...>
Date: 2004-02-19T01:41:41+09:00
Subject: Re: Builtins RDoc tarball?

On Thursday, February 19, 2004, 3:02:29 AM, Gavin wrote:

> That was the case, where 'old' is 1.8.1, and not a 1.9 snapshot.

Yes, unfortunately 1.8.1 just missed the boat on the core API documentation
front.  Still, that means it should be tried and tested in time for
1.8.2.

> Getting 1.9 for rdoc building did the trick. (Or rather, I can see the
> methods of Time now. I'm still fighting to find out what file(s) are
> causing rdoc to crash when writing the output) Thanks :)

Thanks for the persistence.  We need to shake these problems out.


> While I've got you here...is there a way to get rdoc to document 
> multiple call sequences for a method in a .rb file? I tried mimicking
> the style seen in time.c:

> /*
>   *  call-seq:
>   *     Time.at( aTime ) => time
>   *     Time.at( seconds [, microseconds] ) => time

> But putting that same sort of code in myfile.rb:

> #  call-seq:
> #     MutableTime.foo( a )
> #     MutableTime.foo( b )

> ...failed to produce the same results.

No, it's a C workaround.  RDoc can't parse an adequate method header
from C code, because default parameters are done indirectly, and maybe
other reasons.

I'd rather all methods look the same in RDoc output, and that the
'sameness' be modelled on the way Ruby is parsed.  I can see the
benefit in the case of Time.at, above, but...

(OTOH, I'm grateful that RDoc can understand C at all...)

Cheers,
Gavin