Austin Ziegler
10/23/2003 5:18:00 AM
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