fxruby-users

[Fxruby-users] [ANN] Updated API Documentation

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

All,

I've completed the first pass through the FXRuby API documentation, 
which is posted here:

     http://www.fxruby.org/doc/api

By first pass, I simply mean that I think all of the classes and their 
methods and attributes are at least *listed* here. IMO this is now a 
much better choice than reading the C++ API documentation and trying to 
"translate" that from C++ to Ruby. For example, all of the messages that 
various widgets can send to their targets are documented.

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.

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

Thanks,

Lyle

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

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

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

Hugh Sasse Staff Elec Eng wrote:

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

OK, just made a note of this. But to answer the question, no, the return 
value of FXClass.new is always a reference to the new instance, and is 
not affected by the presence or absence of a block.

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

Your point is well taken. A lot of the more interesting information 
about classes like FXDC is not their API in isolation, but rather how 
they plug into the surrounding framework and interact with other classes 
(like FXCanvas). At the least, I should be able to link to other classes 
and methods that RDoc knows about (i.e. a "see also" approach). Not sure 
what facilities, if any, RDoc provides for a more general solution to 
the challenge of cross-referencing related ideas.

By the way, thanks for making me look up the answer to the riddle. I 
will let others google for the answer as I did ;)

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

Which flexibility are you talking about? Attaching a device context (DC) 
to a canvas before you can draw into it?

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

Have you seen the class browser from FreeRIDE? It doesn't work exactly 
as you described, but it's a pretty nifty tool for working with Ruby 
code. It could perhaps be extended to do some of the kinds of the things 
you're describing.

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

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

On Mon, 9 Jun 2003, Lyle Johnson wrote:

> Hugh Sasse Staff Elec Eng wrote:
>
> > true or false.  Does this affect the return value for <a method>?....
>
> OK, just made a note of this. But to answer the question, no, the return

Thank you.
>
> > 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
>
> Your point is well taken. A lot of the more interesting information
> about classes like FXDC is not their API in isolation, but rather how
> they plug into the surrounding framework and interact with other classes

Yes, that's better expressed than I put it.

> (like FXCanvas). At the least, I should be able to link to other classes
> and methods that RDoc knows about (i.e. a "see also" approach). Not sure

Thanks.
> what facilities, if any, RDoc provides for a more general solution to
> the challenge of cross-referencing related ideas.

I know it can have cross references, but I don't think it can
genrate them.
>
> By the way, thanks for making me look up the answer to the riddle. I
> will let others google for the answer as I did ;)

! I thought it had been around a while, so it would be well known.
:-)
>
> > 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.
>
> Which flexibility are you talking about? Attaching a device context (DC)
> to a canvas before you can draw into it?

Yes, for that particular case.  I'm not sure what others there are.
>
> > [...]creating FXRdoc, [...]
>
> Have you seen the class browser from FreeRIDE? It doesn't work exactly

Good point. I have to explore that.  Is it very tied to Scite, or
can I use it with Vim?
>
>
        Thank you
        Hugh

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

[Lyle J. <ly...@kn...>]

Hugh Sasse Staff Elec Eng wrote:

> Good point. I have to explore [FreeRIDE's class browser].  Is it very tied to Scite, or
> can I use it with Vim?

No, I think it's pretty heavily tied into its integrated editor based on 
Scintilla (the same source code editing component used by SciTE).

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

[Joel V. <vj...@PA...>]

Hugh Sasse Staff Elec Eng wrote:

>>what facilities, if any, RDoc provides for a more general solution to
>>the challenge of cross-referencing related ideas.

You all probably know this, but rdoc will automatically link things like

   #method
   Class#method
   Class.class_method

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

[Joel V. <vj...@PA...>]

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

Is this more or less the same as the downloadable api-docs file on the 
sourceforge site?

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

[Lyle J. <ly...@kn...>]

Joel VanderWerf wrote:

> [Are the online API docs] more or less the same as the downloadable api-docs file on the 
> sourceforge site?

More or less, but the "live" docs at the web site are newer and more 
complete. I'll probably post another downloadable snapshot this 
afternoon. Another option, if you have RDoc installed, is to check out 
the FXRuby source code from CVS and build the docs directly from the 
RDoc sources (as I do).