I've recently started using Ruby, coming from a C++/Java background.

And while there where some idiosyncracies, by and large I was able to be
very productive very quickly.

The application has evolved from a simple script (in the sense that
everything "looks global") to something a bit more complex, with
refactorings towards using objects, a "Test-First-After-The-Fact" approach
:-), and to factoring out library-like elements.

Now, I'm aware that there's always a discussion about strong vs. weak,
static vs. dynamic. The last time I had an opinion about it I had no good
answer to the claim that unit-tests lessen the need for static type
checking.

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).
Of course the first step would be to find a good name (at the very least
"data" is a bit too generic). But what next? How does someone who writes an
API communicate that it makes no sense to send "1" to the categories.
Apparently the unit tests and/or dbc encompass the specification, but does
rdoc or some tool extract any information from them?

Am I the first person to run in this problem? If not, what are other
people's solutions? Do you just look at the source code of any library you
use?

I'm asking this from both points of view:

Many times I have run into some library where I was simply asking myself
"what exactly do I have to put into these parameters to get the method to do
what I want?" More specifically, I had this problem in parts of the REXML
library.

And from the other perspective, what is the Ruby Way (tm) to document
methods to users of your API/framework (or simply your class)?