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

Looking through the existing RDOC documentation I found another
inconsistency. First some background:

The "call-seq" for methods in classes implemented in C are given
explicitly as part of the RDOC documentation entry for each method.

For library classes implemented in Ruby, RDOC picks up the calling
sequence automatically from the Ruby source.

Now to the "problem":

As it is now, these two kinds of methods generate different kinds of
documentation entries (RDOC --> HTML). An example from the Time
class (defined in "time.c" but extended in "lib/time.rb"):

-------------------------------------
    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.

I think this inconsistency ought to be resolved.
I don't know which of the alternatives looks best, but right now it
looks kind of silly (especially when the mix occurs inside a single
class, but even between different classes).

The alternative chosen also affects how the description of a method
should be most naturally worded. Now some method descriptions call
their receiver something (e.g. "self") while the the "call-seq"
calls the receiver something different (e.g. "array" or "arr").

What do say ?

/Johan Holmberg