From: Calvelo Daniel <dcalvelo@...2.fr>
Date: 2000-07-03T12:26:57+00:00
Subject: [ruby-talk:03765] Re: Ruby coding standard?

[me]
> Because I tend to test my programs with the interactive interpreter, I use
> this feature to look for usage messages, usage warnings and the like.
> Most of the standard library has docstring documentation. The WHAT part 
> I mentioned above is what may go into docstrings, along with some WHY.

[Mathieu Bouchard]
: Well, I'd like to keep the WHY part separate from the WHAT; this means
: either separate sets of docstrings. Note that the WHY is probably not
: occurring for every method, but rather applies to a group of methods, an
: interface implementation, a whole class implementation, or even the
: relationship between several classes. Writing "WHY" docstrings about
: single methods is probably pointless.

I agree. A module docstring should document the "WHY", the relationships 
with other modules, and I think it should also contain a "contents" part, 
giving an overview of the modules' architecture (contents and features).

[me]
> As for signatures, of course Ruby is not typed. But routines may require
> their arguments to respond to specific messages. it is IMHO useful to
> state some set of requirements on the arguments of a function.

[Mathieu Bouchard]
: In Java you can define interfaces (a set of methods signatures), specify
: interfaces that a class implements, specify interfaces that parameters
: must implement. Is that what you are thinking about?

Fairly close. Java interfaces enforce (rather than document) the number and
type of methods and arguments to be used by implementors of the interface.
I was thinking of having the same information available as documentation 
only.

Current modules in the standard library are documented using embedded doc. 
This provides useful information about parameters to be passed and type of
objects returned. What I'm advocating is that such info would be wonderful
to have in IDEs and interactive interpreters. 

Whether this should be part of the language (as it is in Python but not 
currently in Ruby) or the tool (IDE or other) responsibility is subject 
to debate, though. I favor the former (with one slight glitch: it becomes 
very hard to consistently internationalize docstrings).

-- Daniel Calvelo Aros
     calvelo@lifl.fr