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

[Hugh S. S. E. E. <hg...@dm...>]

On Thu, 3 Jul 2003, Lyle Johnson wrote:

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

Yes, and may be wider, for OO languages in general.

> 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

or a descendent of it,
> "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

Yes, did both of those.
>
> 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 ;)

I wonder if that can be facilitated in some way?  Objects are
supposed to be re-useable, but without docs they won't be.  Maybe
common usage "patterns" might be helpful.

For example, with a teaspoon you can stir tea with it, or eat with
it, and you want to wash it afterwards.  This doesn't mean you can't
use it as a tyre lever when mending a puncture on a bicycle, but at
least the common things inherited from spoon and cutlery are to hand
in the docs.

I'd hope that the tool could search the usual inheritance paths to
find thes methods and link to them, which would save on duplication,
and cope with some ancestor overriding its parent's methods later.

This would be too naive in the case of singletons, but is it worth
consideration, in the general case?  It would not be perfert, but
would it be enough of an improvement to try?

        Hugh