Material: document the attached style properties

Change-Id: I8349ec366c75b9480533bb9b61a3748e09e9560e
Reviewed-by: J-P Nurmi <jpnurmi@qt.io>

2 files changed, 15 insertions, 0 deletions

diff --git a/src/imports/controls/material/qquickmaterialstyle.cpp b/src/imports/controls/material/qquickmaterialstyle.cpp
index beb2b49b..9361e535 100644
--- a/src/imports/controls/material/qquickmaterialstyle.cpp
+++ b/src/imports/controls/material/qquickmaterialstyle.cpp
@@ -369,6 +369,9 @@ static const QRgb colors[][14] = {
     }
 };
 
+// If no value was inherited from a parent or explicitly set, the "global" values are used.
+// The initial, default values of the globals are hard-coded here, but the environment
+// variables and .conf file override them if specified.
 static QQuickMaterialStyle::Theme globalTheme = QQuickMaterialStyle::Light;
 static uint globalPrimary = QQuickMaterialStyle::Indigo;
 static uint globalAccent = QQuickMaterialStyle::Pink;
@@ -378,6 +381,8 @@ static uint globalBackground = 0xFFFAFAFA; // backgroundColorLight
 // Each style's m_hasForeground/m_hasBackground are initialized to these values.
 static bool hasGlobalForeground = false;
 static bool hasGlobalBackground = false;
+// These represent whether or not the global color value was specified as one of the
+// values that QColor accepts, as opposed to one of the pre-defined colors like Red.
 static bool globalPrimaryCustom = false;
 static bool globalAccentCustom = false;
 static bool globalForegroundCustom = true;
diff --git a/src/imports/controls/material/qquickmaterialstyle_p.h b/src/imports/controls/material/qquickmaterialstyle_p.h
index 7572d38c..044d30d9 100644
--- a/src/imports/controls/material/qquickmaterialstyle_p.h
+++ b/src/imports/controls/material/qquickmaterialstyle_p.h
@@ -259,17 +259,27 @@ private:
     QColor buttonColor(bool highlighted, bool pressed, bool hover) const;
     Shade themeShade() const;
 
+    // These reflect whether a color value was explicitly set on the specific
+    // item that this attached style object represents.
     bool m_explicitTheme;
     bool m_explicitPrimary;
     bool m_explicitAccent;
     bool m_explicitForeground;
     bool m_explicitBackground;
+    // These reflect whether the color value that was either inherited or
+    // explicitly set is in the form that QColor expects, rather than one of
+    // our pre-defined color enum values.
     bool m_customPrimary;
     bool m_customAccent;
     bool m_customForeground;
     bool m_customBackground;
+    // These will be true when this item has an explicit or inherited foreground/background
+    // color, or these colors were declared globally via settings (e.g. conf or env vars).
+    // Some color properties of the style will return different values depending on whether
+    // or not these are set.
     bool m_hasForeground;
     bool m_hasBackground;
+    // The actual values for this item, whether explicit, inherited or globally set.
     Theme m_theme;
     uint m_primary;
     uint m_accent;