[doc] Inconsistent indentation of rdoc entries ?

The embedded doc entries in for example array.c are not consistently
indented. What is considered the "right" way ?

I have found normal text of a description aligned like (see the end
for examples):

  1) one space from the "*" in the left margin (like Array#frozen?)

  2) indented like the "method call" in the call-seq description
     (like Array#push)

  3) like the "call-seq" line

This variation doesn't look nice and I think it can lead to errors
(like the one with Array#pack I described in my previous mail).

I think it would be good to use one type of indentation
systematically for the documentation of all methods.

Personally I prefer alternative 1) above.
When 2 or more spaces are used, it becomes increasingly difficult to
see visually how many spaces should actually be used, for example in
a description with several paragraphs with normal text, and
interspersed examples (like Array#pack).

Thoughts ?

/Johan Holmberg


-------------------------------------------------------------------------
/*
 * call-seq:
 *   array.push(obj, ... )   => array
 *
 *   Append---Pushes the given object(s) on to the end of this array. This
 *   expression returns the array itself, so several appends
 *   may be chained together.
 *
 *     a = [ "a", "b", "c" ]
 *     a.push("d", "e", "f")
 *             #=> ["a", "b", "c", "d", "e", "f"]
 */
-------------------------------------------------------------------------
/*
 * call-seq:
 *   array.frozen?  => true or false
 *
 * Return <code>true</code> if this array is frozen (or temporarily frozen
 * while being sorted).
 */
-------------------------------------------------------------------------