Document palette as a basic QML type

Unfortunately we need to manually add some \sa "palette QML Basic Type"
links as a workaround until auto-linking to basic QML types in QML
property headers is fixed in QDoc.

Task-number: QTBUG-63469
Change-Id: I2ea853bfeda31905468741eb720f4daa242e703d
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>

5 files changed, 113 insertions, 67 deletions

diff --git a/src/imports/controls/doc/src/qtquickcontrols2-configuration.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-configuration.qdoc
index 23e52705..33cfcdc8 100644
--- a/src/imports/controls/doc/src/qtquickcontrols2-configuration.qdoc
+++ b/src/imports/controls/doc/src/qtquickcontrols2-configuration.qdoc
@@ -142,71 +142,8 @@
     WindowText=#212121
     \endcode
 
-    Supported palette attributes:
-    \table
-        \header
-            \li Variable
-            \li Description
-        \row
-            \li \l {QPalette::ColorRole}{\c Window}
-            \li A general background color.
-        \row
-            \li \l {QPalette::ColorRole}{\c WindowText}
-            \li A general foreground color.
-        \row
-            \li \l {QPalette::ColorRole}{\c Base}
-            \li Used mostly as the background color for text editor controls and items views.
-                It is usually white or another light color.
-        \row
-            \li \l {QPalette::ColorRole}{\c Text}
-            \li The foreground color used with \c Base. This is usually the same as the \c WindowText,
-                in which case it must provide good contrast with \c Window and \c Base.
-        \row
-            \li \l {QPalette::ColorRole}{\c Button}
-            \li The general button background color. This background can be different from \c Window
-                as some styles require a different background color for buttons.
-        \row
-            \li \l {QPalette::ColorRole}{\c ButtonText}
-            \li A foreground color used with the \c Button color.
-        \row
-            \li \l {QPalette::ColorRole}{\c BrightText}
-            \li A text color that is very different from \c WindowText, and contrasts well with e.g. \c Dark.
-                Typically used for text that needs to be drawn where \c Text, \c WindowText or \c ButtonText
-                would give poor contrast, such as on highlighted buttons.
-        \row
-            \li \l {QPalette::ColorRole}{\c ToolTipBase}
-            \li Used as the background color for tooltips.
-        \row
-            \li \l {QPalette::ColorRole}{\c ToolTipText}
-            \li Used as the foreground color for tooltips.
-
-        \row
-            \li \l {QPalette::ColorRole}{\c Light}
-            \li Lighter than \c Button.
-        \row
-            \li \l {QPalette::ColorRole}{\c Midlight}
-            \li Between \c Button and \c Light.
-        \row
-            \li \l {QPalette::ColorRole}{\c Dark}
-            \li Darker than \c Button.
-        \row
-            \li \l {QPalette::ColorRole}{\c Mid}
-            \li Between \c Button and \c Dark.
-        \row
-            \li \l {QPalette::ColorRole}{\c Shadow}
-            \li A very dark color.
-
-        \row
-            \li \l {QPalette::ColorRole}{\c Highlight}
-            \li A color to indicate a selected item or the current item.
-        \row
-            \li \l {QPalette::ColorRole}{\c HighlightedText}
-            \li A text color that contrasts with \c Highlight.
-
-        \row
-            \li \l {QPalette::ColorRole}{\c Link}
-            \li A text color used for hyperlinks.
-    \endtable
+    See \l {qtquickcontrols2-palette}{palette QML Basic Type} for a full list of supported
+    attributes.
 
     \section1 Using the Configuration File in a Project
 
diff --git a/src/imports/controls/doc/src/qtquickcontrols2-palette.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-palette.qdoc
new file mode 100644
index 00000000..e4bac54a
--- /dev/null
+++ b/src/imports/controls/doc/src/qtquickcontrols2-palette.qdoc
@@ -0,0 +1,107 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \qmlbasictype palette
+    \brief a palette of colors.
+    \target qtquickcontrols2-palette
+
+    The \c palette type refers to a palette of colors for various roles.
+
+    Available properties:
+    \table
+        \header
+            \li Property
+            \li Description
+        \row
+            \li \b palette.alternateBase : color
+            \li Used as the alternate background color in item views with alternating row colors.
+        \row
+            \li \b palette.base : color
+            \li Used mostly as the background color for text editor controls and items views.
+                It is usually white or another light color.
+        \row
+            \li \b palette.brightText : color
+            \li A text color that is very different from \c palette.windowText, and contrasts
+                well with e.g. \c palette.dark. Typically used for text that needs to be drawn
+                where \c palette.text, \c palette.windowText or \c palette.buttonText would
+                give poor contrast, such as on highlighted buttons.
+        \row
+            \li \b palette.button : color
+            \li The general button background color. This background can be different from
+                \c palette.window as some styles require a different background color for buttons.
+        \row
+            \li \b palette.buttonText : color
+            \li A foreground color used with the \c palette.button color.
+        \row
+            \li \b palette.dark : color
+            \li Darker than \c palette.button.
+        \row
+            \li \b palette.highlight : color
+            \li A color to indicate a selected item or the current item.
+        \row
+            \li \b palette.highlightedText : color
+            \li A text color that contrasts with \c palette.highlight.
+        \row
+            \li \b palette.light : color
+            \li Lighter than \c palette.button.
+        \row
+            \li \b palette.link : color
+            \li A text color used for hyperlinks.
+        \row
+            \li \b palette.linkVisited : color
+            \li A text color used for already visited hyperlinks.
+        \row
+            \li \b palette.mid : color
+            \li Between \c palette.button and \c palette.dark.
+        \row
+            \li \b palette.midlight : color
+            \li Between \c palette.button and \c palette.light.
+        \row
+            \li \b palette.shadow : color
+            \li A very dark color.
+        \row
+            \li \b palette.text : color
+            \li The foreground color used with \c palette.base. This is usually the same as
+                the \c palette.windowText, in which case it must provide good contrast with
+                \c palette.window and \c palette.base.
+        \row
+            \li \b palette.toolTipBase : color
+            \li Used as the background color for tooltips.
+        \row
+            \li \b palette.toolTipText : color
+            \li Used as the foreground color for tooltips.
+        \row
+            \li \b palette.window : color
+            \li A general background color.
+        \row
+            \li \b palette.windowText : color
+            \li A general foreground color.
+    \endtable
+
+    \sa Control::palette, Popup::palette, ApplicationWindow::palette, QPalette::ColorRole
+*/
diff --git a/src/quicktemplates2/qquickapplicationwindow.cpp b/src/quicktemplates2/qquickapplicationwindow.cpp
index 2ef84a17..222ceb52 100644
--- a/src/quicktemplates2/qquickapplicationwindow.cpp
+++ b/src/quicktemplates2/qquickapplicationwindow.cpp
@@ -718,7 +718,7 @@ void QQuickApplicationWindow::resetLocale()
     property on the window's palette, that property propagates to all child controls in the window,
     overriding any system defaults for that property.
 
-    \sa Control::palette
+    \sa Control::palette, Popup::palette, {qtquickcontrols2-palette}{palette QML Basic Type}
 */
 QPalette QQuickApplicationWindow::palette() const
 {
diff --git a/src/quicktemplates2/qquickcontrol.cpp b/src/quicktemplates2/qquickcontrol.cpp
index e72df944..14b8e253 100644
--- a/src/quicktemplates2/qquickcontrol.cpp
+++ b/src/quicktemplates2/qquickcontrol.cpp
@@ -1361,6 +1361,8 @@ void QQuickControl::setContentItem(QQuickItem *item)
         }
     }
     \endcode
+
+    \sa ApplicationWindow::palette, Popup::palette, {qtquickcontrols2-palette}{palette QML Basic Type}
 */
 QPalette QQuickControl::palette() const
 {
diff --git a/src/quicktemplates2/qquickpopup.cpp b/src/quicktemplates2/qquickpopup.cpp
index 95e3d553..472d2124 100644
--- a/src/quicktemplates2/qquickpopup.cpp
+++ b/src/quicktemplates2/qquickpopup.cpp
@@ -1505,7 +1505,7 @@ void QQuickPopup::resetFont()
     }
     \endcode
 
-    \sa Control::palette, ApplicationWindow::palette
+    \sa Control::palette, ApplicationWindow::palette, {qtquickcontrols2-palette}{palette QML Basic Type}
 */
 QPalette QQuickPopup::palette() const
 {