On Thu, 19 Aug 2004 02:26:59 +0900, Nicolai Czempin
<nicolai.czempin / alcatel.de> wrote:
> Now that I have gulped down the basics of ruby, I'm starting writing unit
> tests, from the point of view of "what would a user of this class expect".
> And I'm running into what seems to be a fundamental question, and my
> googling so far hasn't turned up any satisfactory answer:

> When I define a method in a class, let's say initialize(categories, data)
> for the sake of argument: In Java etc. I can see from the method definition
> that categories is an ordered set, and data is a Map (and if that info is
> not sufficient, javadoc can be used to explain in more detail what is
> expected, but I'll leave that out for the moment, it's not really key to the
> question).

Actually, it *is* key to the question, as it's (basically) the Ruby
answer without using external mechanisms[1] like StrongTyping,
csinterface, or other mechanisms. Look at Diff::LCS as an example. The
main method is Diff::LCS.diff(seq1, seq2, callback =
Diff::LCS::DiffCallback). If you know what 'diff' does, then you'll be
able to make a good guess that you'll get something back similar to
'diff' when you pass in seq1 or seq2. But what are seq1 and seq2,
precisely? According to my documentation, they are ordered sequences.
I should be a bit more accurate in the definition, as they do require
random access under the current implementation, but they must be
either String-like or Array-like (Array-like works best, because
Strings work on a per-character basis).

The more confusing part is the callback parameter. There's absolutely
no way that I could meaningfully define the callback on the parameter
list, as it's a truly duck-typing situation. Using the #sdiff, I could
come up with a MatchingCallback that would only return those lines
that are considered equivalent. The only sensible solution here is
documentation.

My first step for any library I use is to look over its documentation
and examples to see basic usage. Preferably example use. Most of the
folks who have written libraries for Ruby have been sensible in their
choices, and they "make sense." After that, I look at the source if
I'm still confused.

-austin
[1] External to Ruby itself. rdoc and ri are now part of the Ruby distribution.
-- 
Austin Ziegler * halostatue / gmail.com
               * Alternate: austin / halostatue.ca