From: Jacob Fugal <lukfugl@...>
Date: 2006-06-17T06:25:37+09:00
Subject: Re: Is API documentation useless for learning?

On 6/16/06, Eric Armstrong <Eric.Armstrong@sun.com> wrote:
> When it comes to making improvements, Wiki pages are
> terrific. I created InstallingRuby and InstallingRubyGems
> pages at http://wiki.rubygarden.org/Ruby, for the very
> reason that I wanted to give back to the community. When
> I can make things easier for someone coming along behind
> me, I figure I've done my job.
>
> I'll be happy to add material to the API comments, as
> well. But it would be easier to do if there were some
> sort of Wiki mechanism for that purpose.

Thanks for contributing to the wiki. There's actually a work in
progress which allows Ruby API docs which allow wiki style
annotations, which the maintainer could then roll back into the
"official" doc. I think this would be a great system. I believe the
package is called Rannotate. The idea was thrown out of including this
into ruby-doc.org itself, but I don't think anything's been done about
it.

> So, that said, what's the best way to feedback info into
> the APIs? Do I need to access the source code? If so,
> where is it? The ruby-doc site doesn't have a link. I
> tried rexml.sourceforge, but that doesn't exist. REXML's
> home page has a link to Kou's Documentation Page, but
> that link is broken. I can download the development
> tree from that site, it gives no indication of how to
> feedback any changes.
>
> In short, I would love to add the following notes to
> the API docs, somewhere:
>
>     node_type
>      --returns a symbol
>          :attribute -- use node.value to get text
>          :comment   -- use node.to_s to get text
>          :text      -- use node.value to get text
>          :cdata       (maybe. not verified)
>          :element   -- see below
>
>     node.attribute("attributeName")
>        --returns an attribute node . Use .value on the
>          attribute node (like a text node) to get it's string
>
>     each
>       --iterates over all child nodes
>         see also: each_element, each_recursive
>
>     to_a
>       --returns an array of child nodes

The best place would probably be to post it on the ruby-doc mailing
list (yup, there is one!).

Jacob Fugal