From: Eric Armstrong <Eric.Armstrong@...>
Date: 2006-06-17T07:10:55+09:00
Subject: Re: Wiki page for API docs

Ask and your wish shall be granted! I just found an API
doc Wiki (I think).

I was at the REXML doc page, looking at Node.to_s
http://www.ruby-doc.org/stdlib/libdoc/rexml/rdoc/

That undocumented method had this inscrutable bit of
code, that does't seem to do anything at all, as far
as I can tell:

    def to_s indent=-1
      rv = ""
      write rv,indent
      rv
    end

I'm sure it does /something/, so in an attempt to find
out what, I took a look at the Node.rb file.

There, I saw "To view or add comments on this documentation, 
please go to the API wiki."

I've been clicking everything I can find there, and for the
life of me I don't see any way to get to an actual API
page you can edit, but someone is clearly thinking in the
right direction!

Jacob Fugal wrote:
> 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
>