Better documentation for Color#alpha

[rubyFeedback]

Hello,

I am currently adding support for "HTML colours", as symbol,
in the quite little ruby-gosu code I wrote or adapted from other
people (I learn best when there are examples from other people
that work; unfortunately quite many examples in the showcase
area no longer work, in particular older code) such as rather
than, say:

color  = 0xff_ffffff

To use:

color = :steelblue # It's not 0xff_ffffff, but you get my idea here.

Anyway. Because I am so used to RGB values or HTML colour names
, naturally I am looking at:

Gosu::Color.rgba()

Unless I made a mistake, though, it seems as if we have to
provide the a value (fourth parameter) as well.

I am thinking it may be better to instead use a default value
of 255 here, aka to denote the user saying "ruby and gosu,
I want to show coloured text on the screen, so this should
not be transparent, as it is otherwise quite pointless,
and I would prefer to be able to omit this rather than
having to specify this as-is".

TL; DR: So I think the default should be 255.

By the way, I looked at:

https://www.rubydoc.info/github/gosu/gosu/master/Gosu/Color#argb-class_method

It does not mention the meaning of alpha 0 versus alpha
255. It is no big deal because I can experiment, but I
would highly recommend to mention it explicitely in the
document above; or add a link to wherever the explanation
is.

I rememember having read on the gosu-showcase in the forum
that you are not sure where to mention and document stuff,
e. g. rdoc or github wiki. I highly recommend to just put
it into rdoc. I understand that it should not be "over-documented",
but I think a brief mention of the difference of alpha 0
versus alpha 255, should suffice. (One can reason that
people know what these values mean, but not everyone will,
in particular newcomers or hobby-hackers. In ruby-gtk
for example, they kind of use 0 up to 1 values nowadays,
which I found strange; I much prefer the 0 to 255 range,
as I am so used to it.)

PS: I don't mention specifying RGB as such to, say, 0 or
255, simply because I think the alpha value is less
useful, whereas RGB are fine, so I don't mind them
being mandatory really.

[mblumtritt]

I would suggest to implement it in a separate extension. The Gosu gem itself should provide basic access to all functionality only (keep it lean!).

(I currently check if I can provide my used Gosu extensions (tool functions and stuff) as separate gem soon.)

[jlnr]

Unless I made a mistake, though, it seems as if we have to
provide the a value (fourth parameter) as well.

No mistake! But there is another method Gosu::Color.rgb that only requires three arguments. Now that you mention it, I think having a default value for the fourth parameter in Gosu::Color.rgba would have been a good choice as well. But now it's too late to remove rgb, and therefore I also don't think the default value in rgba is needed.

You are right that Color#alpha is a little under-documented in rdoc, a PR would be welcome, but I can also try to remember it the next time I clean up the source code.