[Fxruby-users] OO documentation issues.
Status: Inactive
Brought to you by:
lyle
From: Hugh S. S. E. E. <hg...@dm...> - 2003-06-11 11:35:33
|
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 |