Re: [Fxruby-users] [ANN] Updated API Documentation

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

On Mon, 9 Jun 2003, Lyle Johnson wrote:

> All,
>
> I've completed the first pass through the FXRuby API documentation,
> which is posted here:
>
>      http://www.fxruby.org/doc/api
>

Thank you for this work....

> More can and should be done. On the "second pass", I want to do a better
> job of documenting the types of the method arguments. For example, take
> a look at the documentation for FX4Splitter's initialize method:
>
>      http://www.fxruby.org/doc/api/classes/Fox/FX4Splitter.html
>
> Here, the individual method arguments and their types are listed in a
> sort of table, similar to the format used for JavaDoc. I'd like to use
> this approach throughout the documentation.

Yes, this is really nice.  Concise and informative.  Also it may
help to add information about what happens when block_given?() is
true or false.  Does this affect the return value for <a method>?....

>
> Another goal is to add short code examples, where appropriate. I'm
> trying to decide what is the right balance between reference
> documentation -- which is the intent -- and the more expositional style

Links to examples that are shipped with FXRuby might be good.  You
have a few that rely on the FXCanvas for example, but I found
reading the code too confusing to learn from, and the API
documentation is rather obscure about how to draw on a canvas.  It
seems, from looking at the draw methods, that you don't draw on an
FXCanvas, you draw on an FXDC.  [cf "How do you get down from an
elephant?"]  The media independence is good, but for someone coming
from Tk this is odd :-)  So how to connect this related semantic
information?  Maybe have a "See also:" item at the end?  "Keywords"?
"CategoryCategories" as per Wiki?  Interesting problem....

I find myself wondering if this flexibility should be exposed
to every programmer, or whether a simpler wrapper might be useful
for the neophyte or the writer of the quick, throwaway bit of code.


> that you will see in the FXRuby book, due out in approximately the year
> 2020 ;)
>
> Anyways, hope this is useful and please give me some feedback about what
> other kinds of information we can show here.


Drifting off topic a bit: Thinking about the different ways people
look at code, and changing viewpoint dynamically, I wondered about
the difficulties of creating FXRdoc, a graphical explorer of code
which allows one to see trees of classes, expose all the constants a
class inherits at once, or just its own, toggle showing of method
code, .....


>
> Thanks,
>
> Lyle
>

        Hugh