From: Eric Armstrong <Eric.Armstrong@...>
Date: 2006-06-15T10:27:39+09:00
Subject: Re: Processing mixed content with REXML

Thanks for the comments, Robert. I don't mind that
RI isn't as good at javadoc about displaying
inherited methods. That's a javadoc feature that
happened to be implemented at my request.

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.)

I started from the REXML home page, which took
me here for the APIs:
http://www.germane-software.com/software/XML/rexml/doc/

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.

<rant>
I like Ruby. A lot. But it's murderous trying to
figure out how to get anything done. I've never been
much of a code reader. (Character flaw, I admit.)
But I guess I'll have to become one.

But if that's the case, what's the point of publishing
API documents? Why should I read them, if needed APIs are
quietly ignored? How would I even /know/ that an API was
absent?
</rant>

On the other hand, you do seem to have given me two
great tips:

   * Use IRB to find out what an object is capable of
   * Use a Class method, #inspect

IRB has never been proposed from that perspective before.
That's a new idea. I got this far:

   require 'rexml/Document'
   include REXML

I tried Element#inspect, but all that gave me was
   => REXML::Element

That's not very helpful. What's the final part of this
very helpful trick?

thanks again
eric






Robert Klemme wrote:
> 2006/6/14, Eric Armstrong <Eric.Armstrong@sun.com>:
>> You did indeed speak truly. Thank you very much.
>>
>> Notes for the Element API docs:
>>
>>     node_type --returns a symbol
>>        :comment, :element, :text (I've seen these)
>>        :cdata, ???      (I expect these)
> 
> I don't think you will see them. CDATA is really just a way to 
> encapsulate text.
> 
>>     each --iterates over all child nodes
> 
> That's written in the docs.
> 
>>     to_a --returns an array of child nodes
> 
> That's also written in the docs. Remember that by including modules
> multiple inheritance is at work. Granted that RI isn't as good as
> pointing out all the methods as JavaDoc but then again these can
> change at runtime anyway.  It usually helps to look at things in IRB
> or #inspect them.
> 
>> Where is a good place to add these?
>> (In other words, is there a way to do it without
>> checking out the project?)
> 
> IMHO not needed.
> 
> Have you been on the REXML homepage? There's pretty good docs and
> tutorials there
> http://www.germane-software.com/software/rexml/
> 
> Cheers
> 
> robert
>