From: Chad Fowler <chad@...>
Date: 2003-10-22T10:16:10+09:00
Subject: Re: RDoc and i18n

On Wed, 22 Oct 2003, Austin Ziegler wrote:

# [edited because there's two different discussions]
# 
# On Wed, 22 Oct 2003 03:12:30 +0900, Dave Thomas wrote:
# > We've all seen the problems that arise now when documentation is
# > separate from code, and the code changes. I'd like to try to avoid
# > this.
# 
# In general, I agree. However, there was a conversation on #ruby-talk
# a few weeks ago (where I started looking at this) that suggested
# that there are cases when the inline documentation is, well, too
# much. There are cases when RDoc makes really good API documentation,
# but doesn't work as well when you're reading the source itself. (The
# complaint was specifically about methods that are really self-
# documenting, such as #<=>.)
# 

I was part of that conversation.  I think I may have even started it if 
it's the one I'm thinking of.

I didn't feel like RDoc itself was in some way in need of a change.  I was 
critiquing what I think is non-value-adding documentation such as:

  # Remove an element from the list
  def remove_from_list(element)
    @list.remove(element)
  end

Chad