Document QGtk3Storage

Add internal documentation to header and implementation of
QGtk3Storage.

Pick-to: 6.5
Change-Id: I8e12dad57c2458dea4446cddc8df1ceef59c070c
Reviewed-by: Shawn Rutledge <shawn.rutledge@qt.io>

2 files changed, 193 insertions, 39 deletions

diff --git a/src/plugins/platformthemes/gtk3/qgtk3storage.cpp b/src/plugins/platformthemes/gtk3/qgtk3storage.cpp
index de0fea4139..1319157f44 100644
--- a/src/plugins/platformthemes/gtk3/qgtk3storage.cpp
+++ b/src/plugins/platformthemes/gtk3/qgtk3storage.cpp
@@ -24,7 +24,26 @@ QGtk3Storage::QGtk3Storage()
     populateMap();
 }
 
-// Set a brush from a source and resolve recursions
+/*!
+    \internal
+    \enum QGtk3Storage::SourceType
+    \brief This enum represents the type of a color source.
+
+    \value Gtk Color is read from a GTK widget
+    \value Fixed A fixed brush is specified
+    \value Modified The color is a modification of another color (fixed or read from GTK)
+    \omitvalue Invalid
+ */
+
+/*!
+    \internal
+    \brief Find a brush from a source.
+
+    Returns a QBrush from a given \param source and a \param map of available brushes
+    to search from.
+
+    A null QBrush is returned, if no brush corresponding to the source has been found.
+ */
 QBrush QGtk3Storage::brush(const Source &source, const BrushMap &map) const
 {
     switch (source.sourceType) {
@@ -64,7 +83,14 @@ QBrush QGtk3Storage::brush(const Source &source, const BrushMap &map) const
     Q_UNREACHABLE();
 }
 
-// Find source for a recursion and take dark/light/unknown into consideration
+/*!
+    \internal
+    \brief Recurse to find a source brush for modification.
+
+    Returns the source specified by the target brush \param b in the \param map of brushes.
+    Takes dark/light/unknown into consideration.
+    Returns an empty brush if no suitable one can be found.
+ */
 QGtk3Storage::Source QGtk3Storage::brush(const TargetBrush &b, const BrushMap &map) const
 {
 #define FIND(brush) if (map.contains(brush))\
@@ -88,7 +114,16 @@ QGtk3Storage::Source QGtk3Storage::brush(const TargetBrush &b, const BrushMap &m
 #undef FIND
 }
 
-// Create a simple standard palette
+/*!
+    \internal
+    \brief Returns a simple, hard coded base palette.
+
+    Create a hard coded palette with default colors as a fallback for any color that can't be
+    obtained from GTK.
+
+    \note This palette will be used as a default baseline for the system palette, which then
+    will be used as a default baseline for any other palette type.
+ */
 QPalette QGtk3Storage::standardPalette()
 {
     QColor backgroundColor(0xd4, 0xd0, 0xc8);
@@ -105,7 +140,13 @@ QPalette QGtk3Storage::standardPalette()
     return palette;
 }
 
-// Deliver a palette styled according to the current GTK Theme
+/*!
+    \internal
+    \brief Return a GTK styled QPalette.
+
+    Returns the pointer to a (cached) QPalette for \param type, with its brushes
+    populated according to the current GTK theme.
+ */
 const QPalette *QGtk3Storage::palette(QPlatformTheme::Palette type) const
 {
     if (type >= QPlatformTheme::NPalettes)
@@ -160,6 +201,12 @@ const QPalette *QGtk3Storage::palette(QPlatformTheme::Palette type) const
     return &m_paletteCache[type].value();
 }
 
+/*!
+    \internal
+    \brief Return a GTK styled font.
+
+    Returns a QFont of \param type, styled according to the current GTK theme.
+*/
 const QFont *QGtk3Storage::font(QPlatformTheme::Font type) const
 {
     if (m_fontCache[type].has_value())
@@ -169,6 +216,13 @@ const QFont *QGtk3Storage::font(QPlatformTheme::Font type) const
     return &m_fontCache[type].value();
 }
 
+/*!
+    \internal
+    \brief Return a GTK styled standard pixmap if available.
+
+    Returns a pixmap specified by \param standardPixmap and \param size.
+    Returns an empty pixmap if GTK doesn't support the requested one.
+ */
 QPixmap QGtk3Storage::standardPixmap(QPlatformTheme::StandardPixmap standardPixmap,
                                      const QSizeF &size) const
 {
@@ -186,11 +240,19 @@ QPixmap QGtk3Storage::standardPixmap(QPlatformTheme::StandardPixmap standardPixm
     return QPixmap::fromImage(image.scaled(size.toSize()));
 }
 
+/*!
+    \internal
+    \brief Returns a GTK styled file icon corresponding to \param fileInfo.
+ */
 QIcon QGtk3Storage::fileIcon(const QFileInfo &fileInfo) const
 {
     return m_interface ? m_interface->fileIcon(fileInfo) : QIcon();
 }
 
+/*!
+    \internal
+    \brief Clears all caches.
+ */
 void QGtk3Storage::clear()
 {
     m_appearance = Qt::Appearance::Unknown;
@@ -202,6 +264,13 @@ void QGtk3Storage::clear()
         cache.reset();
 }
 
+/*!
+    \internal
+    \brief Handles a theme change at runtime.
+
+    Clear all caches, re-populate with current GTK theme and notify the window system interface.
+    This method is a callback for the theme change signal sent from GTK.
+ */
 void QGtk3Storage::handleThemeChange()
 {
     clear();
@@ -209,6 +278,54 @@ void QGtk3Storage::handleThemeChange()
     QWindowSystemInterface::handleThemeChange();
 }
 
+/*!
+    \internal
+    \brief Populates a map with information about how to locate colors in GTK.
+
+    This method creates a data structure to locate color information for each brush of a QPalette
+    within GTK. The structure can hold mapping information for each QPlatformTheme::Palette
+    enum value. If no specific mapping is stored for an enum value, the system palette is returned
+    instead of a specific one. If no mapping is stored for the system palette, it will fall back to
+    QGtk3Storage::standardPalette.
+
+    The method will populate the data structure with a standard mapping, covering the following
+    palette types:
+    \list
+    \li QPlatformTheme::SystemPalette
+    \li QPlatformTheme::CheckBoxPalette
+    \li QPlatformTheme::RadioButtonPalette
+    \li QPlatformTheme::ComboBoxPalette
+    \li QPlatformTheme::GroupBoxPalette
+    \li QPlatformTheme::MenuPalette
+    \li QPlatformTheme::TextLineEditPalette
+    \endlist
+
+    The method will check the environment variable {{QT_GUI_GTK_JSON_SAVE}}. If it points to a
+    valid path with write access, it will write the standard mapping into a Json file.
+    That Json file can be modified and/or extended.
+    The Json syntax is
+    - "QGtk3Palettes" (top level value)
+        - QPlatformTheme::Palette
+            - QPalette::ColorRole
+                - Qt::Appearance
+                - Qt::ColorGroup
+                - Source data
+                    - Source Type
+                        - [source data]
+
+    If the environment variable {{QT_GUI_GTK_JSON_HARDCODED}} contains the keyword \c true,
+    all sources are converted to fixed sources. In that case, they contain the hard coded HexRGBA
+    values read from GTK.
+
+    The method will also check the environment variable {{QT_GUI_GTK_JSON}}. If it points to a valid
+    Json file with read access, it will be parsed instead of creating a standard mapping.
+    Parsing errors will be printed out with qCInfo if the logging category {{qt.qpa.gtk}} is activated.
+    In case of a parsing error, the method will fall back to creating a standard mapping.
+
+    \note
+    If a Json file contains only fixed brushes (e.g. exported with {{QT_GUI_GTK_JSON_HARDCODED=true}}),
+    no colors will be imported from GTK.
+ */
 void QGtk3Storage::populateMap()
 {
     static QString m_themeName;
@@ -248,6 +365,15 @@ void QGtk3Storage::populateMap()
         qWarning() << "File" << jsonOutput << "could not be saved.\n";
 }
 
+/*!
+    \internal
+    \brief Return a palette map for saving.
+
+    This method returns the existing palette map, if the environment variable
+    {{QT_GUI_GTK_JSON_HARDCODED}} is not set or does not contain the keyword \c true.
+    If it contains the keyword \c true, it returns a palette map with all brush
+    sources converted to fixed sources.
+ */
 const QGtk3Storage::PaletteMap QGtk3Storage::savePalettes() const
 {
     const QString hard = qEnvironmentVariable("QT_GUI_GTK_JSON_HARDCODED");
@@ -282,21 +408,50 @@ const QGtk3Storage::PaletteMap QGtk3Storage::savePalettes() const
     return map;
 }
 
+/*!
+    \internal
+    \brief Saves current palette mapping to a \param filename with Json format \param f.
+
+    Saves the current palette mapping into a QJson file,
+    taking {{QT_GUI_GTK_JSON_HARDCODED}} into consideration.
+    Returns \c true if saving was successful and \c false otherwise.
+ */
 bool QGtk3Storage::save(const QString &filename, QJsonDocument::JsonFormat f) const
 {
     return QGtk3Json::save(savePalettes(), filename, f);
 }
 
+/*!
+    \internal
+    \brief Returns a QJsonDocument with current palette mapping.
+
+    Saves the current palette mapping into a QJsonDocument,
+    taking {{QT_GUI_GTK_JSON_HARDCODED}} into consideration.
+    Returns \c true if saving was successful and \c false otherwise.
+ */
 QJsonDocument QGtk3Storage::save() const
 {
     return QGtk3Json::save(savePalettes());
 }
 
+/*!
+    \internal
+    \brief Loads palette mapping from Json file \param filename.
+
+    Returns \c true if the file was successfully parsed and \c false otherwise.
+ */
 bool QGtk3Storage::load(const QString &filename)
 {
     return QGtk3Json::load(m_palettes, filename);
 }
 
+/*!
+    \internal
+    \brief Creates a standard palette mapping.
+
+    The method creates a hard coded standard mapping, used if no external Json file
+    containing a valid mapping has been specified in the environment variable {{QT_GUI_GTK_JSON}}.
+ */
 void QGtk3Storage::createMapping()
 {
     // Hard code standard mapping
@@ -332,41 +487,39 @@ void QGtk3Storage::createMapping()
 #define CLEAR map.clear()
 
     /*
-     *  Macro ussage:
-     *
-     *  1. Define a source
-     *
-     *  GTK(QGtkWidget, QGtkColorSource, GTK_STATE_FLAG)
-     *  Fetch the color from a GtkWidget, related to a source and a state.
-     *
-     *  LIGHTER(ColorGroup, ColorROle, lighter)
-     *  Use a color of the same QPalette related to ColorGroup and ColorRole.
-     *  Make the color lighter (if lighter >100) or darker (if lighter < 100)
-     *
-     *  MODIFY(ColorGroup, ColorRole, red, green, blue)
-     *  Use a color of the same QPalette related to ColorGroup and ColorRole.
-     *  Modify it by adding red, green, blue.
-     *
-     *  FIX(const QBrush &)
-     *  Use a fixed brush without querying GTK
-     *
-     *  2. Define the target
-     *
-     *  Use ADD(ColorGroup, ColorRole) to use the defined source for the
-     *  color group / role in the current palette.
-     *
-     *  Use ADD(ColorGroup, ColorRole, Appearance) to use the defined source
-     *  only for a specific appearance
-     *
-     *  3. Save mapping
-     *  Save the defined mappings for a specific palette.
-     *  If a mapping entry does not cover all color groups and roles of a palette,
-     *  the system palette will be used for the remaining values.
-     *  If the system palette does not have all combination of color groups and roles,
-     *  the remaining ones will be populated by a hard coded fusion-style like palette.
-     *
-     *  4. Clear mapping
-     *  Use CLEAR to clear the mapping and begin a new one.
+       Macro usage:
+
+       1. Define a source
+       GTK(QGtkWidget, QGtkColorSource, GTK_STATE_FLAG)
+       Fetch the color from a GtkWidget, related to a source and a state.
+
+       LIGHTER(ColorGroup, ColorROle, lighter)
+       Use a color of the same QPalette related to ColorGroup and ColorRole.
+       Make the color lighter (if lighter >100) or darker (if lighter < 100)
+
+       MODIFY(ColorGroup, ColorRole, red, green, blue)
+       Use a color of the same QPalette related to ColorGroup and ColorRole.
+       Modify it by adding red, green, blue.
+
+       FIX(const QBrush &)
+       Use a fixed brush without querying GTK
+
+       2. Define the target
+       Use ADD(ColorGroup, ColorRole) to use the defined source for the
+       color group / role in the current palette.
+
+       Use ADD(ColorGroup, ColorRole, Appearance) to use the defined source
+       only for a specific appearance
+
+       3. Save mapping
+       Save the defined mappings for a specific palette.
+       If a mapping entry does not cover all color groups and roles of a palette,
+       the system palette will be used for the remaining values.
+       If the system palette does not have all combination of color groups and roles,
+       the remaining ones will be populated by a hard coded fusion-style like palette.
+
+       4. Clear mapping
+       Use CLEAR to clear the mapping and begin a new one.
      */
 
 
diff --git a/src/plugins/platformthemes/gtk3/qgtk3storage_p.h b/src/plugins/platformthemes/gtk3/qgtk3storage_p.h
index 57f6aeea96..af628d49ff 100644
--- a/src/plugins/platformthemes/gtk3/qgtk3storage_p.h
+++ b/src/plugins/platformthemes/gtk3/qgtk3storage_p.h
@@ -33,6 +33,7 @@ class QGtk3Storage
 public:
     QGtk3Storage();
 
+    // Enum documented in cpp file. Please keep it in line with updates made here.
     enum class SourceType {
         Gtk,
         Fixed,