Doc: decrease confusion about HSV vs HSL in QColor

The non-qualified hue() and saturation() etc. refers to those values
in the HSV, not HSL, color model. Make this more explicit in the
documentation to avoid confusion.

Task-number: QTBUG-73129
Change-Id: Ief337672966ac72d0d0c3606d8d68acf01ffe7ee
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>

1 files changed, 37 insertions, 29 deletions

diff --git a/src/gui/painting/qcolor.cpp b/src/gui/painting/qcolor.cpp
index 1f1835d5da..e5bac84df9 100644
--- a/src/gui/painting/qcolor.cpp
+++ b/src/gui/painting/qcolor.cpp
@@ -541,7 +541,15 @@ static QStringList get_colornames()
     \section1 The HSL Color Model
 
     HSL is similar to HSV, however instead of the Value parameter, HSL
-    specifies a Lightness parameter.
+    specifies a Lightness parameter which maps somewhat differently to the
+    brightness of the color.
+
+    Similarly, the HSL saturation value is not in general the same as the HSV
+    saturation value for the same color. hslSaturation() provides the color's
+    HSL saturation value, while saturation() and hsvSaturation() provides the
+    HSV saturation value.
+
+    The hue value is defined to be the same in HSL and HSV.
 
     \section1 The CMYK Color Model
 
@@ -1098,7 +1106,7 @@ void QColor::setHsv(int h, int s, int v, int a)
     These components can be retrieved individually using the hslHueF(),
     hslSaturationF(), lightnessF() and alphaF() functions.
 
-    \sa setHsl()
+    \sa getHsl(), setHslF(), {QColor#The HSL Color Model}{The HSL Color Model}
 */
 void QColor::getHslF(qreal *h, qreal *s, qreal *l, qreal *a) const
 {
@@ -1128,7 +1136,7 @@ void QColor::getHslF(qreal *h, qreal *s, qreal *l, qreal *a) const
     These components can be retrieved individually using the hslHue(),
     hslSaturation(), lightness() and alpha() functions.
 
-    \sa setHsl()
+    \sa getHslF(), setHsl(), {QColor#The HSL Color Model}{The HSL Color Model}
 */
 void QColor::getHsl(int *h, int *s, int *l, int *a) const
 {
@@ -1619,11 +1627,11 @@ void QColor::setBlueF(qreal blue)
 }
 
 /*!
-    Returns the hue color component of this color.
+    Returns the HSV hue color component of this color.
 
     The color is implicitly converted to HSV.
 
-    \sa hsvHue(), hueF(), getHsv(), {QColor#The HSV Color Model}{The HSV Color Model}
+    \sa hsvHue(), hslHue(), hueF(), getHsv(), {QColor#The HSV Color Model}{The HSV Color Model}
 */
 
 int QColor::hue() const Q_DECL_NOTHROW
@@ -1632,9 +1640,9 @@ int QColor::hue() const Q_DECL_NOTHROW
 }
 
 /*!
-    Returns the hue color component of this color.
+    Returns the HSV hue color component of this color.
 
-    \sa hueF(), getHsv(), {QColor#The HSV Color Model}{The HSV Color Model}
+    \sa hueF(), hslHue(), getHsv(), {QColor#The HSV Color Model}{The HSV Color Model}
 */
 int QColor::hsvHue() const Q_DECL_NOTHROW
 {
@@ -1644,11 +1652,11 @@ int QColor::hsvHue() const Q_DECL_NOTHROW
 }
 
 /*!
-    Returns the saturation color component of this color.
+    Returns the HSV saturation color component of this color.
 
     The color is implicitly converted to HSV.
 
-    \sa hsvSaturation(), saturationF(), getHsv(), {QColor#The HSV Color Model}{The HSV Color
+    \sa hsvSaturation(), hslSaturation(), saturationF(), getHsv(), {QColor#The HSV Color Model}{The HSV Color
     Model}
 */
 
@@ -1658,9 +1666,9 @@ int QColor::saturation() const Q_DECL_NOTHROW
 }
 
 /*!
-    Returns the saturation color component of this color.
+    Returns the HSV saturation color component of this color.
 
-    \sa saturationF(), getHsv(), {QColor#The HSV Color Model}{The HSV Color Model}
+    \sa saturationF(), hslSaturation(), getHsv(), {QColor#The HSV Color Model}{The HSV Color Model}
 */
 int QColor::hsvSaturation() const Q_DECL_NOTHROW
 {
@@ -1682,11 +1690,11 @@ int QColor::value() const Q_DECL_NOTHROW
 }
 
 /*!
-    Returns the hue color component of this color.
+    Returns the HSV hue color component of this color.
 
     The color is implicitly converted to HSV.
 
-    \sa hsvHueF(), hue(), getHsvF(), {QColor#The HSV Color Model}{The HSV Color Model}
+    \sa hsvHueF(), hslHueF(), hue(), getHsvF(), {QColor#The HSV Color Model}{The HSV Color Model}
 */
 qreal QColor::hueF() const Q_DECL_NOTHROW
 {
@@ -1696,7 +1704,7 @@ qreal QColor::hueF() const Q_DECL_NOTHROW
 /*!
     Returns the hue color component of this color.
 
-    \sa hue(), getHsvF(), {QColor#The HSV Color Model}{The HSV Color
+    \sa hue(), hslHueF(), getHsvF(), {QColor#The HSV Color Model}{The HSV Color
     Model}
 */
 qreal QColor::hsvHueF() const Q_DECL_NOTHROW
@@ -1707,11 +1715,11 @@ qreal QColor::hsvHueF() const Q_DECL_NOTHROW
 }
 
 /*!
-    Returns the saturation color component of this color.
+    Returns the HSV saturation color component of this color.
 
      The color is implicitly converted to HSV.
 
-    \sa hsvSaturationF(), saturation(), getHsvF(), {QColor#The HSV Color Model}{The HSV Color
+    \sa hsvSaturationF(), hslSaturationF(), saturation(), getHsvF(), {QColor#The HSV Color Model}{The HSV Color
     Model}
 */
 qreal QColor::saturationF() const Q_DECL_NOTHROW
@@ -1720,9 +1728,9 @@ qreal QColor::saturationF() const Q_DECL_NOTHROW
 }
 
 /*!
-    Returns the saturation color component of this color.
+    Returns the HSV saturation color component of this color.
 
-    \sa saturation(), getHsvF(), {QColor#The HSV Color Model}{The HSV Color Model}
+    \sa saturation(), hslSaturationF(), getHsvF(), {QColor#The HSV Color Model}{The HSV Color Model}
 */
 qreal QColor::hsvSaturationF() const Q_DECL_NOTHROW
 {
@@ -1746,9 +1754,9 @@ qreal QColor::valueF() const Q_DECL_NOTHROW
 /*!
     \since 4.6
 
-    Returns the hue color component of this color.
+    Returns the HSL hue color component of this color.
 
-    \sa getHslF(), getHsl()
+    \sa hslHueF(), hsvHue(), getHsl(), {QColor#The HSL Color Model}{The HSL Color Model}
 */
 int QColor::hslHue() const Q_DECL_NOTHROW
 {
@@ -1760,9 +1768,9 @@ int QColor::hslHue() const Q_DECL_NOTHROW
 /*!
     \since 4.6
 
-    Returns the saturation color component of this color.
+    Returns the HSL saturation color component of this color.
 
-    \sa saturationF(), getHsv(), {QColor#The HSV Color Model}{The HSV Color Model}
+    \sa hslSaturationF(), hsvSaturation(), getHsl(), {QColor#The HSL Color Model}{The HSL Color Model}
 */
 int QColor::hslSaturation() const Q_DECL_NOTHROW
 {
@@ -1788,9 +1796,9 @@ int QColor::lightness() const Q_DECL_NOTHROW
 /*!
     \since 4.6
 
-    Returns the hue color component of this color.
+    Returns the HSL hue color component of this color.
 
-    \sa hue(), getHslF()
+    \sa hslHue(), hsvHueF(), getHslF()
 */
 qreal QColor::hslHueF() const Q_DECL_NOTHROW
 {
@@ -1802,9 +1810,9 @@ qreal QColor::hslHueF() const Q_DECL_NOTHROW
 /*!
     \since 4.6
 
-    Returns the saturation color component of this color.
+    Returns the HSL saturation color component of this color.
 
-    \sa saturationF(), getHslF()
+    \sa hslSaturation(), hsvSaturationF(), getHslF(), {QColor#The HSL Color Model}{The HSL Color Model}
 */
 qreal QColor::hslSaturationF() const Q_DECL_NOTHROW
 {
@@ -2124,7 +2132,7 @@ QColor QColor::toHsv() const Q_DECL_NOTHROW
 /*!
     Creates and returns an HSL QColor based on this color.
 
-    \sa fromHsl(), convertTo(), isValid()
+    \sa fromHsl(), convertTo(), isValid(), {QColor#The HSL Color Model}{The HSL Color Model}
 */
 QColor QColor::toHsl() const Q_DECL_NOTHROW
 {
@@ -2436,7 +2444,7 @@ QColor QColor::fromHsvF(qreal h, qreal s, qreal v, qreal a)
     The value of \a s, \a l, and \a a must all be in the range 0-255; the value
     of \a h must be in the range 0-359.
 
-    \sa toHsl(), fromHslF(), isValid()
+    \sa toHsl(), fromHslF(), isValid(), {QColor#The HSL Color Model}{The HSL Color Model}
 */
 QColor QColor::fromHsl(int h, int s, int l, int a)
 {
@@ -2468,7 +2476,7 @@ QColor QColor::fromHsl(int h, int s, int l, int a)
 
     All the values must be in the range 0.0-1.0.
 
-    \sa toHsl(), fromHsl(), isValid()
+    \sa toHsl(), fromHsl(), isValid(), {QColor#The HSL Color Model}{The HSL Color Model}
 */
 QColor QColor::fromHslF(qreal h, qreal s, qreal l, qreal a)
 {