From: James Britt <jamesUNDERBARb@...>
Date: 2004-08-19T05:40:52+09:00
Subject: Re: Documenting a class interface when there are no types in the method signature

Nicolai Czempin wrote:
> I've recently started using Ruby, coming from a C++/Java background.
> ...
> 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?

Sometimes, though I'd prefer not to.  Too lazy.

It helps when the arguments have meaningful names.

> 
> 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)?

I don't know about The Ruby Way, but when I have a method that will 
accept different sorts of objects for the same parameter, I simple note 
that in the rdoc.

There are (at least) two types of object substitution.  In one, the 
method is basically expecting, say, a String, but really only cares that 
it responds to one or two String methods.

In the other case, the method knows that it might receive objects of a 
limited set.  For example, a method for XML processing that knows what 
to do if given either a String or a REXML Document.

In the first case, the parameter name might be enough to indicate what 
to pass in.  In the second case, some explicit docs are needed to make 
clear that one can pass either something that acts like a String, or 
something that acts like a REXML Document.  (Well, you could use a 
parameter named 'xml_as_either_string_or_REXML_doc'.)

I'm thinking, though, that this is not so much a dynamic typing issue, 
but a problem for API design and documentation in general.  For example, 
simply knowing that some Java method requires a Collection object may 
not be enough.  A Collection of what?  The method name, and the names of 
the parameters, need to express the reason the method exists and why you 
might be interested in using it.

Even when you know the exact type for a parameter, you still have to 
know the range of acceptable or meaningful values.  Sometimes the best 
way for a developer to indicate that is to simply write it down.


James