doc: Attempt to clarify how the factor of color's mix() function is applied

api/cpp/include/slint_color.h

@@ -153,8 +153,9 @@ public:
     /// The transparency is obtained by multiplying the alpha channel by `(1 - factor)`.
     [[nodiscard]] inline Color transparentize(float factor) const;
 
-    /// Returns a new color that is a mix of \a this and \a other, with a proportion
+    /// Returns a new color that is a mix of \a this color and \a other. The specified \a factor is
-    /// factor given by \a factor (which will be clamped to be between `0.0` and `1.0`).
+    /// clamped to be between `0.0` and `1.0` and then applied to \a this color, while `1.0 -
+    /// factor` is applied to \a other.
     [[nodiscard]] inline Color mix(const Color &other, float factor) const;
 
     /// Returns a new version of this color with the opacity set to \a alpha.

api/node/src/types/brush.rs

@@ -142,8 +142,9 @@ impl SlintRgbaColor {
         SlintRgbaColor::from(self.inner.transparentize(amount as f32))
     }
 
-    /// Returns a new color that is a mix of `self` and `other`, with a proportion
+    /// Returns a new color that is a mix of `this` color and `other`. The specified factor is
-    /// factor given by `factor` (which will be clamped to be between `0.0` and `1.0`).
+    /// clamped to be between `0.0` and `1.0` and then applied to `this` color, while `1.0 - factor`
+    ///is applied to `other`.
     #[napi]
     pub fn mix(&self, other: &SlintRgbaColor, factor: f64) -> SlintRgbaColor {
         SlintRgbaColor::from(self.inner.mix(&other.inner, factor as f32))

docs/reference/src/language/syntax/types.md

@@ -95,8 +95,10 @@ All colors and brushes define the following methods:
 
 -   **`mix(other: brush, factor: float) -> brush`**
 
-    Returns a new color that is a mix of this color and `other`, with a proportion
+    Returns a new color that is a mix of this color and `other`. The specified factor is
-    factor given by factor (which will be clamped to be between `0.0` and `1.0`).
+    clamped to be between `0.0` and `1.0` and then applied to this color, while `1.0 - factor`
+    is applied to `other`. For example `red.mix(green, 70%)` will have a stronger tone of red, while
+    `red.mix(green, 30%)` will have a stronger tone of green.
 
 -  **`transparentize(factor: float) -> brush`**
 

internal/core/graphics/color.rs

@@ -234,8 +234,9 @@ impl Color {
         color
     }
 
-    /// Returns a new color that is a mix of `self` and `other`, with a proportion
+    /// Returns a new color that is a mix of this color and `other`. The specified factor is
-    /// factor given by `factor` (which will be clamped to be between `0.0` and `1.0`).
+    /// clamped to be between `0.0` and `1.0` and then applied to this color, while `1.0 - factor`
+    /// is applied to `other`.
     ///
     /// # Examples
     /// Mix red with black half-and-half:
@@ -246,7 +247,7 @@ impl Color {
     /// assert_eq!(red.mix(&black, 0.5), Color::from_rgb_u8(128, 0, 0));
     /// ```
     ///
-    /// Mix Purple with OrangeRed with `75%`:`25%` ratio:
+    /// Mix Purple with OrangeRed,  with `75%` purpe and `25%` orange red ratio:
     /// ```
     /// # use i_slint_core::graphics::Color;
     /// let purple = Color::from_rgb_u8(128, 0, 128);