From: Austin Ziegler <austin@...>
Date: 2003-10-23T14:17:54+09:00
Subject: Re: RDoc and i18n

On Wed, 22 Oct 2003 10:16:10 +0900, Chad Fowler wrote:
> 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 think you were. I know that David Black was involved in the conversation, 
too.

> 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

You're right. If you have the code immediately available, then such 
documentation *is* NVA. In API documentation, though, I disagree that it's 
NVA. I find it quite annoying to open an rdoc API and find that half of the 
methods aren't documented ... until I open the code window and see that it 
really is a simple method.

As I told Dave, though, there's a problem with the fact that multi-lingual 
documentation is next to impossible if there's any chance of multiple 
encodings. What I've proposed would solve that -- but it would also allow 
for the other item.

-austin
--
austin ziegler    * austin@halostatue.ca * Toronto, ON, Canada
software designer * pragmatic programmer * 2003.10.23
                                         * 00.54.55