From: Eric Armstrong <Eric.Armstrong@...>
Date: 2006-06-16T07:38:05+09:00
Subject: Re: Is API documentation useless for learning?

Kindly ignore previous. The problem with frames.
I was at the home page, not at the Element page.

Observations:

   1) Wow. Parent is a link. Who would have guessed?

   2) Visting that page, it looks familiar. As I
      recall, I found it before by selecting "Parent"
      in the class list.

   3) each, and to_a are indeed listed there--totally
      without comments. I still have to visit the
      source code to find out what they do. (Or
      depend on the kindness of the folks who inhabit
      this forum--which generates a lot of traffic.)

   4) Clicking on the file link shows me a page that
      lists required files, and that's all.

But here's a page that sets the bar for how API
docs should read:
http://builder.rubyforge.org/

There are links to source code for each API. And
clicking on the link displays the code inline.
/Very/ nice. Anyone know how that was created?

   Note:
   Seeing the method without any context turns out
   not to help me very much. But it's way better
   than nothing. For example, class! shows
   _start_container, _css_block, and _unify_block,
   none of which are in the method list!

Implication:
   If had I seen that to_a returned the value of
   "children" for example, I would still need to
   know what that variable contains. Alternatively,
   I need to search for occurrences of "children"
   in the source code, in order to build up that
   understanding. But that takes me back to the
   need to examine source code, once again.

I don't /like/ coming to the conclusion that API
documents have too many gaps to be useful, but I
find myself being forced in that direction--and
thinking about how to solve the problem.


Matthew Smillie wrote:
> First things first:
> 
>>>> When you click on Element, you'll see no mention
>>>> of each or to_a, or any mention of a class that might
>>>> have defined them. There is no comment on node_type,
>>>> and no pointers to code, in lieu of commentary.
> 
> This is related to this:
> 
>>>> But it bugs me that that it doesn't even name
>>>> superclasses. (It /seems/ to name modules, but
>>>> I have no way of knowing if it's complete.)
> 
> 
> Which isn't actually the case.  If you look at the blue title bar, you 
> see this:
> 
> Class: REXML::Element
> In: temp/element.rb
> Parent: Parent
> 
> 'Parent' is the superclass.  If you click on that, you can see that the 
> Parent class includes Enumerable (which would account for a default each 
> method that you seem to be looking for).
> 
> You can find the entire source in 'temp/element.rb', which is a pointer 
> to code, and you can get the source for a method by clicking on its 
> signature (you get a pop-up).
> 
> Reading API docs is a pain, I know, but it does help to know how they 
> work.  Hope this helps a bit.
> 
> matthew smillie.
> 
> 
> 
>