From: Robert Klemme <shortcutter@...>
Date: 2006-06-15T20:24:00+09:00
Subject: Re: Processing mixed content with REXML

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

-- 
Have a look: http://www.flickr.com/photos/fussel-foto/