From: Jacob Fugal <lukfugl@...>
Date: 2006-06-17T08:40:58+09:00
Subject: Re: Wiki page for API docs

On 6/16/06, Eric Armstrong <Eric.Armstrong@sun.com> wrote:
> 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

My guess is that the +write+ method (which is probably private or
protected), writes the actual contents of the tree into its first
argument, using the indentation specified. So we create a string to
write into, pass it on to the write function, then return that string.
Viol�!

But this wasn't really your point, so I'll get on with it...

> 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!

This isn't quite the wiki-annotations I was referring to. Instead what
this is is a wiki page dedicated to each rdoc page. Each of those
pages are blank by default. You're not editing *the* API page, but
rather a page *related* to the API page. The Rannotate library that I
was referring to takes it a step further by allowing you to edit a
chunk *embedded* in the API page, but you still aren't editing the API
documentation itself. Two of the benefits are that there are several
of these chunks per page -- one for each method, as well as one for
the page itself -- and that the notes are viewable inline with the
rest of the documentation.

See http://ruby.outertrack.com/ for an example of Rannotate in action.
(I don't know how many annotations have actually been added there, but
you can play with the functionality.)

Jacob Fugal