From: Eric Armstrong Date: 2006-06-15T11:09:16+09:00 Subject: Re: Is API documentation useless for learning? Arggh. It turns out that a list of behaviors really doesn't solve anything. I see to_a in the list, but so what? That's a pretty standard method. I have no way of knowing what it does. Of course, I can try out all 50-some methods and see if I can figure out what they do. But that's a long way to go to answer a pretty simple question. I guess there is just no alternative. At this point, API documents are beginning to look pretty useless, when it comes to learning how to use a class. That's a shame, because the formatting makes them a lot easier to read. But if they're going to silently ignore the very existence of important APIs, how can I begin to trust them? Frankly, I see this as a pretty big deal when it comes to language acceptance. Alternative opinions would be very welcome. Eric Armstrong wrote: > Found it! > > % irb > require 'rexml/Document' > include REXML > puts Element.methods > > or x = SomeClass.new > puts x.methods > > > Eric Armstrong wrote: >> 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. >> >> >> 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? >> >> >> 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 : >>>> 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 >>> >> >