From: Gavin Sinclair <gsinclair@...>
Date: 2004-02-12T23:59:01+09:00
Subject: Re: Standard libraries

On Friday, February 13, 2004, 12:44:15 AM, Sean wrote:

> On Thursday 12 February 2004 04:37, Gavin Sinclair wrote:
>> Besides, interfaces don't change often, after the software is a little
>> mature.  Method signatures of *implementation* (private, or in non

> Heh.  Famous last words.

> Anyway, on of Ruby's features is a lack of static typing.  Unfortunately, this
> makes it impossible for a tool to determine the type of arguments and
> methods, so this shifts the burden of documentation on the developer.
> Basically, the code duplication that Hiroshi is complaining about is required
> for good documentation, because there's no other way of extracting 
> constraints information from the source code, except by reading it by hand.
> I really don't want to force users to understand all 4,600 lines of REXML
> just to use it; that defeats the purpose of it.

Good points, but I don't see the light overall.

Method documentation is neccesary to help people understand the code -
I agree.  Without type information it can be hard to understand a
method at a glance.

_Therefore_, one should be glad to document important (public or
private) methods, as they help your own understanding, and that of
others who wish to grok the code.  That gladness should alleviate
frustration at the apparent duplication.  Besides, a brief sentence is
enough; you don't need an exact specification.  Code is documentation
in Ruby, and RDoc with inline source is a great code browser :)

Gavin