[Fxruby-users] OO documentation issues.

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

I have been thinking some more about the problems of doucmenting
FXRuby effectively, and why it is a difficult problem.  Gnererally
OO programming simplifies things in so far as when you know about a
calss 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.  For example, one can learn about transistors,
understand their characteristics (current as a function of voltage),
and one may know about resistors, Ohm's law and power dissipation.
This doesn't give enough information to design a transistor
amplifier with correct biasing of the transistor, and desired gain
and input and output impedance.  For this some extensive knowledge
of how the components interact is necessary.

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 calsses 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.  Would a more relevant example help?

Take FXButton.
<quote>
new(parent, text, icon=nil, target=nil, selector=0,
opts=BUTTON_NORMAL, x=0, y=0, width=0, height=0,
padLeft=DEFAULT_PAD, padRight=DEFAULT_PAD, padTop=DEFAULT_PAD,
padBottom=DEFAULT_PAD) {|theButton| ...}

Construct button with specified text and icon.
</quote>

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.

Considering further the context in which these widgets are used,
would it be useful to have links in the docs to unit-tests for the
widget, which explain how each facility is put to use?

        Hugh