[Fxruby-users] Re: API documentation (was: Dialogues, and create)

[Lyle J. <jl...@cf...>]

Hugh Sasse Staff Elec Eng wrote:

>> > Ah, just "clicked" about getApp(), avoids repeoting a ref to the
>> > application object.  getApp doesn't seem to appear in the methods
>> > pane of http://www.fxruby.org/doc/api/
>>
>> It *is* listed as a "readable" attribute of FXId:
> 
> Oh! it's one of those! :-)
> 
>> value. But that's a separate discussion, whether we should be listing
>> both the "getter" and "setter" methods as well as the "attr_reader" and
>> "attr_writer" methods in the API docs ;)
> 
> yes, this may really fall into the "who is RDoc's audience?" area:
> -- I was feeling frustrated earlier trying to find out where show()
> came from, because it is used by FXDialogueBox, but comes from
> FXTopWindow, but FXTopWindow.methods doesn't reveal it, only
> FXTopWindow.instance_methods does.

Right, but this is just a Ruby thing. Object#methods returns a list of 
methods available for the object. Since FXTopWindow is itself an object 
(it is an instance of class "Class"), you can call methods on it to get 
a list of its methods:

     FXTopWindow.methods

but of course this isn't very useful. What you *really* want to know is, 
if you have my hands on an FXTopWindow object (an instance of class 
"FXTopWindow"), what methods can you call on that? So then your choices are:

     aTopWindow = FXTopWindow.new(...)
     aTopWindow.methods

or the more convenient:

     FXTopWindow.instance_methods

> I'm beginning to think that there maybe needs to be another template
 > for RDoc for behaviour discovery. This leads into the dark and
 > twisty passages about respond_to?() being insufficient to specify
 > type because it doesn't cover semantics. So I can't think about adding
 > this to RDoc myself when it is probably not the solution.

Sure. Good automated documentation tools like RDoc are great to have, 
but they can't write the meat of the text for you. As you say, they 
cannot divine the semantics of a particular method given its name, or 
its argument list; some human being has to fill in those blanks ;)