Rework QIcon theme documentation

Generalized the documentation, and clarified behaviors,
in preparation for adding additional platform icon engines.

Change-Id: I4a694dc2cedd08cb195c738048c7dae72cbfe867
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
(cherry picked from commit 17dc1e2152c424343526962ce710cf4b2bbd920d)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

src/gui/image/qicon.cpp

@@ -1121,6 +1121,10 @@ QString QIcon::name() const
     \since 4.6
 
     Sets the search paths for icon themes to \a paths.
+
+    The content of \a paths should follow the theme format
+    documented by setThemeName().
+
     \sa themeSearchPaths(), fromTheme(), setThemeName()
 */
 void QIcon::setThemeSearchPaths(const QStringList &paths)
@@ -1129,20 +1133,14 @@ void QIcon::setThemeSearchPaths(const QStringList &paths)
 }
 
 /*!
-  \since 4.6
+    \since 4.6
 
-  Returns the search paths for icon themes.
+    Returns the search paths for icon themes.
 
-  The default value will depend on the platform:
+    The default search paths will be defined by the platform.
+    All platforms will also have the resource directory \c{:\icons} as a fallback.
 
-  On X11, the search path will use the XDG_DATA_DIRS environment
+    \sa setThemeSearchPaths(), fromTheme(), setThemeName()
-  variable if available.
-
-  By default all platforms will have the resource directory
-  \c{:\icons} as a fallback. You can use "rcc -project" to generate a
-  resource file from your icon theme.
-
-  \sa setThemeSearchPaths(), fromTheme(), setThemeName()
 */
 QStringList QIcon::themeSearchPaths()
 {
@@ -1154,12 +1152,13 @@ QStringList QIcon::themeSearchPaths()
 
     Returns the fallback search paths for icons.
 
-    The fallback search paths are used to look for standalone
+    The fallback search paths are consulted for standalone
     icon files if the \l{themeName()}{current icon theme}
     or \l{fallbackIconTheme()}{fallback icon theme} do
     not provide results for an icon lookup.
 
-    The default value will depend on the platform.
+    If not set, the fallback search paths will be defined
+    by the platform.
 
     \sa setFallbackSearchPaths(), themeSearchPaths()
 */
@@ -1173,12 +1172,12 @@ QStringList QIcon::fallbackSearchPaths()
 
     Sets the fallback search paths for icons to \a paths.
 
-    The fallback search paths are used to look for standalone
+    The fallback search paths are consulted for standalone
     icon files if the \l{themeName()}{current icon theme}
     or \l{fallbackIconTheme()}{fallback icon theme} do
     not provide results for an icon lookup.
 
-    \note To add some path without replacing existing ones:
+    For example:
 
     \snippet code/src_gui_image_qicon.cpp 5
 
@@ -1194,9 +1193,15 @@ void QIcon::setFallbackSearchPaths(const QStringList &paths)
 
     Sets the current icon theme to \a name.
 
-    The \a name should correspond to a directory name in the
+    The theme will be will be looked up in themeSearchPaths().
-    themeSearchPath() containing an index.theme
+
-    file describing its contents.
+    At the moment the only supported icon theme format is the
+    \l{Freedesktop Icon Theme Specification}. The \a name should
+    correspond to a directory name in the themeSearchPath()
+    containing an \c index.theme file describing its contents.
+
+    \externalpage http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html
+    \title Freedesktop Icon Theme Specification
 
     \sa themeSearchPaths(), themeName()
 */
@@ -1210,8 +1215,15 @@ void QIcon::setThemeName(const QString &name)
 
     Returns the name of the current icon theme.
 
-    On X11, the current icon theme depends on your desktop
+    If not set, the current icon theme will be defined by the
-    settings. On other platforms it is not set by default.
+    platform.
+
+    \note Platform icon themes are only implemented on
+    \l{Freedesktop} based systems at the moment, and the
+    icon theme depends on your desktop settings.
+
+    \externalpage https://www.freedesktop.org/
+    \title Freedesktop
 
     \sa setThemeName(), themeSearchPaths(), fromTheme(),
     hasThemeIcon()
@@ -1226,8 +1238,12 @@ QString QIcon::themeName()
 
     Returns the name of the fallback icon theme.
 
-    On X11, if not set, the fallback icon theme depends on your desktop
+    If not set, the fallback icon theme will be defined by the
-    settings. On other platforms it is not set by default.
+    platform.
+
+    \note Platform fallback icon themes are only implemented on
+    \l{Freedesktop} based systems at the moment, and the
+    icon theme depends on your desktop settings.
 
     \sa setFallbackThemeName(), themeName()
 */
@@ -1241,16 +1257,16 @@ QString QIcon::fallbackThemeName()
 
     Sets the fallback icon theme to \a name.
 
-    The fallback icon theme is used for last resort lookup of icons
+    The fallback icon theme is consulted for icons not provided by
-    not provided by the \l{themeName()}{current icon theme},
+    the \l{themeName()}{current icon theme}, or if the \l{themeName()}
-    or if the \l{themeName()}{current icon theme} does not exist.
+    {current icon theme} does not exist.
 
-    The \a name should correspond to a directory name in the
+    The \a name should correspond to theme in the same format
-    themeSearchPath() containing an index.theme
+    as documented by setThemeName(), and will be looked up
-    file describing its contents.
+    in themeSearchPaths().
 
-    \note This should be done before creating \l QGuiApplication, to ensure
+    \note Fallback icon themes should be set before creating
-    correct initialization.
+    QGuiApplication, to ensure correct initialization.
 
     \sa fallbackThemeName(), themeSearchPaths(), themeName()
 */
@@ -1262,34 +1278,33 @@ void QIcon::setFallbackThemeName(const QString &name)
 /*!
     \since 4.6
 
-    Returns the QIcon corresponding to \a name in the current
+    Returns the QIcon corresponding to \a name in the
-    icon theme.
+    \l{themeName()}{current icon theme}.
 
-    The latest version of the freedesktop icon specification and naming
+    If the current theme does not provide an icon for \a name,
-    specification can be obtained here:
+    the \l{fallbackIconTheme()}{fallback icon theme} is consulted,
-
+    before falling back to looking up standalone icon files in the
-    \list
+    \l{QIcon::fallbackSearchPaths()}{fallback icon search path}.
-    \li \l{http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html}
-    \li \l{http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html}
-    \endlist
 
     To fetch an icon from the current icon theme:
 
     \snippet code/src_gui_image_qicon.cpp 3
 
-    \note By default, only X11 will support themed icons. In order to
+    If an \l{themeName()}{icon theme} has not been explicitly
-    use themed icons on Mac and Windows, you will have to bundle a
+    set via setThemeName() a platform defined icon theme will
-    compliant theme in one of your themeSearchPaths() and set the
+    be used.
-    appropriate themeName().
 
-    \note Qt will make use of GTK's icon-theme.cache if present to speed up
+    \note Platform icon themes is only implemented on
-    the lookup. These caches can be generated using gtk-update-icon-cache:
+    \l{Freedesktop} based systems at the moment,
-    \l{https://developer.gnome.org/gtk3/stable/gtk-update-icon-cache.html}.
+    following the \l{Freedesktop Icon Naming Specification}.
+    In order to use themed icons on other platforms, you will have
+    to bundle a \l{setThemeName()}{compliant theme} in one of your
+    themeSearchPaths(), and set the appropriate themeName().
 
-    \note If an icon can't be found in the current theme, then it will be
+    \externalpage https://specifications.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html
-    searched in fallbackSearchPaths() as an unthemed icon.
+    \title Freedesktop Icon Naming Specification
 
-    \sa themeName(), setThemeName(), themeSearchPaths(), fallbackSearchPaths()
+    \sa themeName(), fallbackIconTheme(), setThemeName(), themeSearchPaths(), fallbackSearchPaths()
 */
 QIcon QIcon::fromTheme(const QString &name)
 {
@@ -1308,14 +1323,25 @@ QIcon QIcon::fromTheme(const QString &name)
 /*!
     \overload
 
-    Returns the QIcon corresponding to \a name in the current
+    Returns the QIcon corresponding to \a name in the
-    icon theme. If no such icon is found in the current theme
+    \l{themeName()}{current icon theme}.
-    \a fallback is returned instead.
 
-    If you want to provide a guaranteed fallback for platforms that
+    If the current theme does not provide an icon for \a name,
-    do not support theme icons, you can use the second argument:
+    the \l{fallbackIconTheme()}{fallback icon theme} is consulted,
+    before falling back to looking up standalone icon files in the
+    \l{QIcon::fallbackSearchPaths()}{fallback icon search path}.
+
+    If no icon is found \a fallback is returned.
+
+    This is useful to provide a guaranteed fallback, regardless of
+    whether the current set of icon themes and fallbacks paths
+    support the requested icon.
+
+    For example:
 
     \snippet code/src_gui_image_qicon.cpp 4
+
+    \sa fallbackIconTheme(), fallbackSearchPaths()
 */
 QIcon QIcon::fromTheme(const QString &name, const QIcon &fallback)
 {
@@ -1331,7 +1357,8 @@ QIcon QIcon::fromTheme(const QString &name, const QIcon &fallback)
     \since 4.6
 
     Returns \c true if there is an icon available for \a name in the
-    current icon theme, otherwise returns \c false.
+    current icon theme or any of the fallbacks, as described by
+    fromTheme(), otherwise returns \c false.
 
     \sa themeSearchPaths(), fromTheme(), setThemeName()
 */