From: Eric Armstrong <Eric.Armstrong@...>
Date: 2006-06-16T07:19:16+09:00
Subject: Re: Processing mixed content with REXML

/Excellent/ tips. Thanks much. I'll digest and apply.

Robert Klemme wrote:
> 2006/6/15, Eric Armstrong <Eric.Armstrong@sun.com>:
>> 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.
> 
> I didn't even notice that your email address end in @sun.com when I
> wrote the last message.  Funny.
> 
>> 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.)
> 
> While I'll readily agree that RI and documentation is not too good in
> Ruby I have to disagree here.  If you closely look at Element's
> documentation you'll see that the superclass Parent is mentioned in
> the header as well as included modules (Namespace in this case). If
> you go to Parent which is hyperlinked you'll see that it includes
> Enumerable - a std lib module that provides a lot of methods based on
> iteration (#each) and #to_a is one of them.
> 
>> 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.
> 
> (see above)
> 
>> <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.
> 
> Not necessarily.  If you really love Ruby that much it's sure no
> problem for you to adapt your approach in obtaining information to
> Ruby's dynamic nature.  :-) These are the things I usually do when
> confronted with an unknown interface:
> 
> - Go to IRB and evaluate obj.methods.sort or obj.methods.grep
> /expected_name/.  You can also use inspect on obj.class.ancestors to
> print out methods by class. Try this in IRB
> 
> [].class.ancestors.inject {|cl,su| p cl, cl.instance_methods -
> su.instance_methods;su}
> 
> - In IRB: Evaluate obj.class.ancestors to see the chain of
> superclasses and supermodules
> 
> - In IRB: do obj.method :a_name to see where it is defined. See
> http://groups.google.com/group/comp.lang.ruby/msg/a6400366930941bc
> 
> - Start out with a script and use any of the above and / or #inspect
> at the point where you want to derive information; in your case that
> would mean to fill the iteration block with something like
> 
> doc.each do |element|
>  p element
>  p element.methods.sort
>  # maybe exit to keep the output readable
> end
> 
> That's fairly easy to do with Ruby because you don't need the compile 
> cycle.
> 
>> 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>
> 
> You are so right.  But remember that even the best API documentation
> cannot deal with methods added at runtime. Sometimes even complete
> modules are included at runtime and you never know until you see the
> object.  So I'd say the incomplete state of the Ruby API documentation
> partly reflects this basic problem of API documentation for a dynamic
> language like Ruby.
> 
>> 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?
> 
> See above.
> 
>> thanks again
> 
> You're welcome.
> 
> Kind regards
> 
> robert
>