fxruby-users

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

[Jacobs, D. <Dee...@Dy...>]

Thanks Lyle,

	This is the sort of changes I asked you about back in May.
This is very helpful for newbies to the GUI. 

I still see trouble in my understanding of some of the interfaces.
An example below from FXImage - Public functions.

mirror(horizontal, vertical)  

Mirror image horizontally and/or vertically 

Does this indicate need for values here for each or is
it a choice of options? What are the expected values?

Please check other places for abiguities.

I very much appreciate your help to us who are new
to API interfaces. Can't get along without them.

Dee A. Jacobs

-----Original Message-----
From: Lyle Johnson [mailto:jl...@cf...]
Sent: Monday, June 09, 2003 12:12 PM
To: fxr...@li...
Subject: [Fxruby-users] [ANN] Updated API Documentation


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



-------------------------------------------------------
This SF.net email is sponsored by:  Etnus, makers of TotalView, The best
thread debugger on the planet. Designed with thread debugging features
you've never dreamed of, try TotalView 6 free at www.etnus.com.
_______________________________________________
Fxruby-users mailing list
Fxr...@li...
https://lists.sourceforge.net/lists/listinfo/fxruby-users

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

[Jacobs, D. <Dee...@Dy...>]

Thanks again, Lyle.
	This is helpful.
	Generic examples, like your foo example are 
	extremely helpful.

	I guess most of my questions will be of the
	specifics as in the mirror item.

	I know you will do a fine job.

Dee A. Jacobs

-----Original Message-----
From: Lyle Johnson [mailto:jl...@cf...]
Sent: Monday, June 09, 2003 1:37 PM
To: fxr...@li...
Subject: Re: [Fxruby-users] [ANN] Updated API Documentation


Jacobs, Dee wrote:

>         This is the sort of changes I asked you about back in May.
> This is very helpful for newbies to the GUI.

Great!

> I still see trouble in my understanding of some of the interfaces.
> An example below from FXImage - Public functions.
> 
> mirror(horizontal, vertical) 
> 
> Mirror image horizontally and/or vertically
> 
> Does this indicate need for values here for each or is
> it a choice of options? What are the expected values?

This indicates a need for both values. If a method has some optional 
argument(s), its declaration will look something like this:

     foo(x, y, z=1)

where the "z=1" notation means that the third argument to the "foo" 
method is optional and, if not specified, assumes a default value of 1.

For your specific question: the FXImage#mirror method takes two 
arguments of boolean type (i.e. true or false). Neither has a default 
value, so you must specify both of them. If the first argument 
(horizontal) is true, the image will be mirrored from left-to-right. If 
the second argument (vertical) is true, the image will be mirrored from 
top-to-bottom. If both are true it's flipped in both directions.

> Please check other places for ambiguities.

I will do my best, but things which are ambiguous to you (or others) are 
not necessarily ambiguous to me. It's going to be a very iterative 
process, but I hope that you and others will help me to improve the docs 
as we go along.

Thanks,

Lyle



-------------------------------------------------------
This SF.net email is sponsored by:  Etnus, makers of TotalView, The best
thread debugger on the planet. Designed with thread debugging features
you've never dreamed of, try TotalView 6 free at www.etnus.com.
_______________________________________________
Fxruby-users mailing list
Fxr...@li...
https://lists.sourceforge.net/lists/listinfo/fxruby-users

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

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

Jacobs, Dee wrote:

>         This is the sort of changes I asked you about back in May.
> This is very helpful for newbies to the GUI.

Great!

> I still see trouble in my understanding of some of the interfaces.
> An example below from FXImage - Public functions.
> 
> mirror(horizontal, vertical) 
> 
> Mirror image horizontally and/or vertically
> 
> Does this indicate need for values here for each or is
> it a choice of options? What are the expected values?

This indicates a need for both values. If a method has some optional 
argument(s), its declaration will look something like this:

     foo(x, y, z=1)

where the "z=1" notation means that the third argument to the "foo" 
method is optional and, if not specified, assumes a default value of 1.

For your specific question: the FXImage#mirror method takes two 
arguments of boolean type (i.e. true or false). Neither has a default 
value, so you must specify both of them. If the first argument 
(horizontal) is true, the image will be mirrored from left-to-right. If 
the second argument (vertical) is true, the image will be mirrored from 
top-to-bottom. If both are true it's flipped in both directions.

> Please check other places for ambiguities.

I will do my best, but things which are ambiguous to you (or others) are 
not necessarily ambiguous to me. It's going to be a very iterative 
process, but I hope that you and others will help me to improve the docs 
as we go along.

Thanks,

Lyle