> We also describe in the text that follows the circumstances under
> which nil is returned.
> The problem is that these "or nil"s appear all over the place (and
> we're discovered places where they're missing), and they mess up the
> layout of the method definitions somewhat. So, we were wondering: do
> people feel they're useful to include in the signature, or is noting
> them in the accompanying text good enough?
>       str.index( aString ) -> aFixnum or nil

Please include them, simply because nil is not a fixnum, and so one has to
check the return value, and act accordingly. it's as simple as that.

matju