From: Dave Thomas <Dave@...>
Date: 2000-07-18T14:24:05-05:00
Subject: [ruby-talk:04114] Method signature - a question for the group


When Andy and I are documenting methods, we like to show a kind of
method signature:

      str.index( aString ) -> aFixnum

or somesuch.

However, String#index can return either a Fixnum or nil, depending on
whether the substring was found, so in this particular case we
document it as

      str.index( aString ) -> aFixnum or nil

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?


Thanks for your help.


Dave