Re: [doc] Inconsistent "call-seq" usage etc.

On Sat, 10 Jul 2004, Dave Thomas wrote:
> > -------------------------------------
> >     time.hour => fixnum
> >
> >     Returns the hour of the day (0..23) for time.
> >     ...
> > -------------------------------------
> >     httpdate()
> >
> >     Returns a string which represents the time as rfc1123-date of
> >     HTTP-date defined by RFC 2616:
> >     ...
> > -------------------------------------
> >
> > Note how the first method description explicitly mentions the
> > receiver (called "time" there), and the second method lets the
> > receiver be implicit.
>
> That's because I had the information available for the C stuff, but
> RDoc can't make up the names for the receiver for Ruby source.
> >
> > I think this inconsistency ought to be resolved.
>
> I'd welcome suggestions and patches.
>

I realize now that there are several differences in the HTML
output from RDoc for Ruby-methods and C-methods:

- in Ruby-methods we don't get any info about the return value

- Ruby-methods are displayed without an explicit receiver

- a Ruby-method will never have a "call-seq description"
  consisting of several alternatives, even if it would be natural
  (for example FileUtils::cd with and without a block)


I don't know enough about the RDoc markup, but as far as I
understand, the documentation of a Ruby-method can't have a
"call-seq" entry (overriding the automatically generated info).

Is this correct ?
Would it be a good thing to add, making it possible to fine-tune the
"synopsis" of a Ruby-method ?
I tend to think so.

And what about return values ?
Would it a good idea to add a special markup to indicate only the
return value ?

I guess one of the original ideas with RDocs markup was that the
"call-seq" would not have to be specified separately, but
automatically extracted from the source code.

What would be in the "spirit" of RDoc ?

/Johan Holmberg