Re: [Fxruby-users] OO documentation issues.

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

Hugh Sasse Staff Elec Eng wrote:

> I have been thinking some more about the problems of documenting
> FXRuby effectively, and why it is a difficult problem.  Generally
> OO programming simplifies things in so far as when you know about a
> class of components you can generalize.  This is good.  However,
> knowing about all the classes doesn't mean you know about how to put
> them together.

Yes, I agree.

> This sort of knowledge lives outside the class descriptions, but
> within the space of the toolkit.  Looking around the fox size I see
> this problem reflected there.  There are classes that interact but
> only have descriptions about themselves, and even in the C++ source
> code comments don't reflect the wider context in which they are
> used.

Again, I of course agree. But I should make it clear that the FXRuby API 
reference documentation is just that, reference material. It is not 
intended as the first stop for someone learning how to use FOX or 
FXRuby, in the same way that you wouldn't want to try to learn how to 
speak French by reading a French-English dictionary.

In an earlier post, I sort-of joked about an FXRuby "book" that would 
fill the sometimes large gap between the example programs and the 
reference documentation. A kind of "Programming FXRuby" or "The FXRuby 
Way", that is more instructive or tutorial-driven instead of just 
presenting the cold, hard facts ;)

> OK, parent and text are clear enough.  Icon refers to bttons with an
> image on them, I take it.  What is target?  Is it to do with Data
> Targets?  What is selector?  Options, position, size and padding are
> relatively clear. Some of these things will interact: what if the
> image is bigger than the button size, or the text wider/taller than
> the button.  Instead of making this whole expression a link to the
> code would it be useful to postprocess the RDoc output so each of
> these keywords is a link to a desciption of the appropriate topic?
> What happens if the parent won't support the creation of a button?
> These sort of questions apply more widely than this case, and I
> don't know where the information should be held so it can be found.

Many of these "wider context" issues are covered in various articles at 
the FOX web site (http://www.fox-toolkit.org/doc.html). To a large 
degree, those articles are language-independent, even if the code 
examples Jereon uses happen to be written in C++. For example, I'm 
pretty sure that all of the material in the chapter on FOX's layout 
managers (http://www.fox-toolkit.org/layout.html) can be applied to 
directly to FXRuby without any mental gymnastics of trying to convert 
from C++ concepts to Ruby concepts.

Once you've learned those fundamental concepts, you should find that 
they work the same throughout the library. For example, once you 
understand how FOX's message-target system works for events generated by 
FXButton (perhaps after reading 
http://www.fox-toolkit.org/messages.html), you'll find that that 
knowledge transfers pretty seamlessly to new widgets. For example, you 
could look at the reference docs for FXSpinner 
(http://www.fxruby.org/doc/api/classes/Fox/FXSpinner.html), scan the 
list of events it sends to its target, and set up handler(s) for those 
messages.

Hope this helps,

Lyle