Update docs on Color to be more clear about normalized channel values.
#160798
Conversation
This comment was marked as outdated.
This comment was marked as outdated.
|
Removed the refactoring so this is 100% a documentation change. |
| /// Color c2 = const Color.fromARGB(0xFF, 0x42, 0xA5, 0xF5); | ||
| /// Color c3 = const Color.fromARGB(255, 66, 165, 245); | ||
| /// Color c4 = const Color.fromRGBO(66, 165, 245, 1.0); | ||
| /// Color c1 = const Color.from(alpha: 1.0, red: 0.2588, green: 0.6471, blue: 0.9608); |
There was a problem hiding this comment.
style nit:
const c1 = Color.from(....)
const c2 = ...
| /// is fully opaque, with a red [r] channel value of `0.2588` (or `0x42` or `66` | ||
| /// as an 8-bit value), a green [g] channel value of `0.6471` (or `0xA5` or | ||
| /// `165` as an 8-bit value), and a blue [b] channel value of `0.9608` (or | ||
| /// `0xF5` or `245` as an 8-bit value). In the common "hash syntax" for RGB |
There was a problem hiding this comment.
Is "hash syntax" a common term? I've only heard it referred to as "hex color". In fact, this seems to be coming straight out of CSS hex color syntax. Maybe we should say exactly that: CSS hex color syntax? And maybe even link to https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color?
There was a problem hiding this comment.
I agree ("hash syntax" was just wording copied from the original docs).
Changed to "CSS hex color syntax" and linked appropriately.
| /// The normalized green channel of this color. | ||
| /// | ||
| /// A value of `0.0` represents no red in this color. A value of `1.0` | ||
| /// represents the maximum amount of greeb. |
| /// > component values (such as `0.5`) into their 8-bit equivalent by using | ||
| /// > the [toARGB32] method; the returned value is not guaranteed to be stable | ||
| /// > across different platforms or executions due to the complexity of | ||
| /// > floating-point math. |
There was a problem hiding this comment.
Might be worth noting that the returned value is compatible with the default constructor (Color.new) but does not guarantee to result in the same color due to imprecisions in numeric conversions.
There was a problem hiding this comment.
Great suggestion, done (albeit done in toARGB32, this is now a stub method as suggested above)
| /// * Bits 8-15 are the green value. | ||
| /// * Bits 0-7 are the blue value. | ||
| /// | ||
| /// > [!WARNING] |
There was a problem hiding this comment.
This warning would be more useful on the non-deprecated toARGB32 method rather than here. In fact, maybe we should turn this dartdoc into a stub that simply points to toARGB32?
gaaclarke
left a comment
There was a problem hiding this comment.
Thanks @matanlurey a good improvement with notes about mentioning 0.0 and 1.0 being the min a max values.
| /// | ||
| /// A value of `0.0` represents no blue in this color. A value of `1.0` | ||
| /// represents the maximum amount of blue. |
There was a problem hiding this comment.
I was very careful about using the word "normalized" or saying 1.0 is the maximum value since internally that isn't the case with ColorSpace.extendedSRGB. It is normalized but 1.0 isn't the max value. Can we remove that sentence please?
| /// Returns a new color with the provided components updated. | ||
| /// | ||
| /// Each component ([alpha], [red], [green], [blue]) represents a normalized | ||
| /// floating-point value wher `0.0` is the minimum and `1.0` is the maximum; |
| /// color space. | ||
| /// If [colorSpace] is provided, and is different than the current color | ||
| /// space, the component values are updated before transforming them to the | ||
| /// provided color space. |
Post-submit feedback from #160798 (review).
Closes #160592.
Made a few other tiny non-breaking refactors, for example changingwithValuesinternally.