From: Austin Ziegler <austin@...>
Date: 2003-10-22T05:21:10+09:00
Subject: Re: RDoc and i18n

[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 #<=>.)

There's also no "clean" way to have RDoc help document the *use* of
a library which may be different than documenting the pure API. This
may help with some of that.

> On Tuesday, Oct 21, 2003, at 13:08 US/Central, Austin Ziegler
> wrote:
>> # :class: Foo
>> # documentation for class Foo.
>> # :method: Foo.bar
>> # documentation for class method Foo.bar
>> # :method: Foo#bar
>> # documentation for instance method Foo#bar.
> On the face of it, I'm not too keen on this kind of approach. The
> philosophy of RDoc is make document transparent, and in the same
> source file as the code.

I agree ... but we *already* have a problem, and that's multi-
lingual documentation. What I'm suggesting is a framework that
allows both multi-lingual and external documentation. RDoc already
merges documentation when it's spread across multiple source files,
doesn't it? Thus, if I put some documentation in the source file and
then more in the external file, the two would be merged into a
single documentation block.

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