On Feb 12, 2004, at 10:19, Sean E. Russell wrote:

>> 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.
>
> Sorry, I wasn't being clear.  I was trying to say that Hiroshi doesn't 
> like
> code duplication, but there is no way to avoid the kind of duplication 
> he's
> complaining about because there's no other way to extract that 
> information
> automatically.

Quite often though you can get away with some common sense parameter 
naming.

    # Iterate over the contents of the AddressBook
    def each_person
       . . .
       yield name, address_book_entry
      . . .
    end

If you RDoc'd that, you'd get


     ------------------------------------------------
     each_person() {|name, address_book_entry| ...}
     -------------------------------------------------
     Iterate over the contents of the AddressBook

Which is probably good enough. I don't think you'd need to add extra 
comments to say that "address_book_entry" is an instancfe of an 
AddressBook..

> I remember having a discussion with Dave about the possibility of 
> having rdoc
> extract constraints from the documentation and generating or running 
> them in
> the form of unit tests.  Dave, I'm a bit out of touch with what you're 
> up to
> these days; have you given this any more thought?
>

I was concerned about the security issues of this, and to be frank 
right now I don't have the time to dig deeper in to it. If someone 
wants to come up with a proposal, and eventually some code, I'm game... 
:)

> Also, since I'm a lazy cuss, does anybody know what the consequenses 
> of having
> Ruby source files that consist of enormous amounts of comments is?

FWIW, I think we need to resist the temptation to add too much 
documentation to the files. I agree with Gavin: a section at the top 
explaining intent and usage, and enough information on each public 
method and class to get someone started. Many public methods get a 
single line comment, some get a lot more.


Cheers

Dave