First steps towards documenting our platform APIs

Adds a new top level topic for platform integration, moving
the QPA docs under that, and cleans up and rewrites the QPA docs
for Qt 6.

Task-number: QTBUG-80233
Change-Id: I658e5e2c402a25ce391102675cee6ada0563e71f
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

9 files changed, 145 insertions, 39 deletions

diff --git a/doc/config/qtdoc.qdocconf b/doc/config/qtdoc.qdocconf
index 2447be4e..be747ce2 100644
--- a/doc/config/qtdoc.qdocconf
+++ b/doc/config/qtdoc.qdocconf
@@ -24,10 +24,10 @@ exampledirs += \
     ../snippets \
     ../../examples
 
-# Don't parse files in snippets and cmake directories
 excludedirs += \
     ../src/snippets \
-    ../src/cmake
+    ../src/cmake \
+    ../src/platformintegration
 
 examplesinstallpath =
 
diff --git a/doc/config/style/qt5-sidebar.html b/doc/config/style/qt5-sidebar.html
index 68abe7fc..4dc62fcf 100644
--- a/doc/config/style/qt5-sidebar.html
+++ b/doc/config/style/qt5-sidebar.html
@@ -40,6 +40,7 @@
         <li><a href="topics-graphics.html">Graphics</a></li>
         <li><a href="mobiledevelopment.html">Mobile APIs</a></li>
         <li><a href="qmlapplications.html">QML Applications</a></li>
+        <li><a href="platform-integration.html">Platform Integration</a></li>
     </ul>
     <ul>
         <li><a href="overviews-main.html">All Qt Overviews</a></li>
diff --git a/doc/src/index.qdoc b/doc/src/index.qdoc
index 4b5fec08..9cad3c2c 100644
--- a/doc/src/index.qdoc
+++ b/doc/src/index.qdoc
@@ -112,6 +112,7 @@
                 \li \l{Integrating Web Content}{Web Content}
                 \li \l{Mobile APIs}
                 \li \l{QML Applications}
+                \li \l{Platform Integration}
                 \endlist
                 \list
                 \li \l{Qt Overviews}{All Qt Overviews}
diff --git a/doc/src/platformintegration/platformintegration.pro b/doc/src/platformintegration/platformintegration.pro
new file mode 100644
index 00000000..470e6659
--- /dev/null
+++ b/doc/src/platformintegration/platformintegration.pro
@@ -0,0 +1,9 @@
+TEMPLATE = aux
+
+QMAKE_DOCS = $$PWD/platformintegration.qdocconf
+
+QTDIR = $$[QT_HOST_PREFIX]
+exists($$QTDIR/.qmake.cache): \
+    QMAKE_DOCS_OUTPUTDIR = $$QTDIR/doc/cmake
+else: \
+    QMAKE_DOCS_OUTPUTDIR = $$OUT_PWD/cmake
diff --git a/doc/src/platformintegration/platformintegration.qdoc b/doc/src/platformintegration/platformintegration.qdoc
new file mode 100644
index 00000000..0957fe8d
--- /dev/null
+++ b/doc/src/platformintegration/platformintegration.qdoc
@@ -0,0 +1,63 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 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$
+**
+****************************************************************************/
+
+/*!
+    \page platform-integration.html
+    \title Platform Integration
+    \brief Integrating Qt with the native platform.
+
+    Qt's main strength as a cross-platform toolkit for application development
+    is removing the need for duplicating the application code for each target
+    platform.
+
+    While Qt solves many of the typical tasks of writing an application,
+    there are always corner cases that Qt can not cover, or where it makes more
+    sense to build a feature on top of the platform specific APIs, or another
+    toolkit.
+
+    To support these use-cases, while still allowing Qt to handle the bulk of
+    the application logic, Qt provides a wide range of platform integration
+    APIs, from simple type conversions to platform specific native interfaces.
+
+    \section1 Type Conversions
+
+    \section1 Window Embedding
+
+    \section1 Native Interfaces
+
+    \section1 Platform Support
+
+    In addition to the application developer APIs, Qt also interfaces with the
+    platform when providing the underlying implementations of the cross-platform
+    building blocks in Qt.
+
+    Examples are the event dispatcher abstractions in \l{Qt Core}, the rendering
+    hardware abstractions in RHI, and the multimedia backends in \l{Qt Multimedia}.
+
+    The main abstraction layer here is the \l{Qt Platform Abstraction},
+    or QPA for short, which deals with window system integration and related use-cases.
+*/
diff --git a/doc/src/platformintegration/platformintegration.qdocconf b/doc/src/platformintegration/platformintegration.qdocconf
new file mode 100644
index 00000000..b0229458
--- /dev/null
+++ b/doc/src/platformintegration/platformintegration.qdocconf
@@ -0,0 +1,21 @@
+include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
+include($QT_INSTALL_DOCS/global/externalsites.qdocconf)
+
+project = QtPlatformIntegration
+navigation.landingpage = "Platform Integration"
+description = "Integrating Qt with the native platform"
+version = $QT_VERSION
+
+depends += qtcore qtgui qtdoc
+sourcedirs = .
+headerdirs = .
+
+moduleheader =
+
+qhp.projects = QtPlatformIntegration
+
+qhp.QtPlatformIntegration.file                = qtplatformintegration.qhp
+qhp.QtPlatformIntegration.namespace           = org.qt-project.qtplatformintegration.$QT_VERSION_TAG
+qhp.QtPlatformIntegration.virtualFolder       = qtplatformintegration
+qhp.QtPlatformIntegration.indexTitle          = "Platform Integration"
+qhp.QtPlatformIntegration.filterAttributes    = qt $QT_VERSION
diff --git a/doc/src/platforms/qpa.qdoc b/doc/src/platformintegration/qpa.qdoc
index df3beb08..b980b63b 100644
--- a/doc/src/platforms/qpa.qdoc
+++ b/doc/src/platformintegration/qpa.qdoc
@@ -29,41 +29,25 @@
 \page qpa.html
 \title Qt Platform Abstraction
 
-The Qt Platform Abstraction (QPA) is the platform abstraction layer for Qt 5
-and replaces Qt for Embedded Linux and the platform ports from Qt 4.
+The Qt Platform Abstraction (QPA) is the main platform abstraction layer in Qt.
 
-QPA plugins are implemented by subclassing various \c QPlatform* classes. There
-are several \e root classes, such as \c QPlatformIntegration and
-\c QPlatformWindow for window system integration and \c QPlatformTheme for
-deeper platform theming and integration. QStyle is not a part of QPA.
+The API can be identified by the \c QPlatform* class prefix, and is used
+for implementing higher level classes typically found in \l{Qt GUI}, e.g.
+\c QPlatformWindow for window system integration exposed through QWindow,
+or \c QPlatformTheme for deeper platform theming and integration, exposed
+through QStyleHint and QStyle.
 
 There are no source or binary compatibility guarantees for the QPA classes,
-meaning that a platform plugin is only guaranteed to work with the Qt version
+meaning that the API is only guaranteed to work with the Qt version
 it was developed against. API changes will however only be made in minor
 releases. (5.1, 5.2, and so on.)
 
-\section1 QPA Minimal Plugins
-
-There is no detailed tutorial documentation for writing QPA plugins at this
-time. However, there are two minimal plugins shipped with Qt 5 for testing and
-other special purposes that you can use as examples:
-
-\list
-\li \c{qtbase/src/plugins/platforms/minimal/}
-\li \c{qtbase/src/plugins/platforms/minimalegl/}
-\endlist
-
-The \c qminimal plugin is used for tools that link against \l{Qt GUI}, but do
-not require window system integration (for example, \c qmlplugindump).
-It also has diagnostic support for dumping window contents to image files
-as determined by environment variables.
-
-\section1 Class Overview
+\section1 API Overview
 
 \list
-\li QPlatformIntegration
+\li Window system integration
     \list
-    \li QAbstractEventDispatcher
+    \li QPlatformIntegration
     \li QPlatformAccessibility
     \li QPlatformBackingStore
     \li QPlatformClipboard
@@ -72,7 +56,6 @@ as determined by environment variables.
     \li QPlatformFontDatabase
     \li QPlatformGraphicsBuffer
     \li QPlatformInputContext
-    \li QPlatformNativeInterface
     \li QPlatformOffscreenSurface
     \li QPlatformOpenGLContext
     \li QPlatformScreen
@@ -82,25 +65,35 @@ as determined by environment variables.
     \li QPlatformWindow
     \endlist
 
-\li QPlatformTheme
+\li Style/theming
+    \list
+    \li QPlatformTheme
+    \li platform palettes
+    \li platform fonts
+    \li theme hints
+    \endlist
+
+\li Native dialogs and menus
     \list
     \li QPlatformDialogHelper
     \li QPlatformMenu
     \li QPlatformMenuBar
     \li QPlatformMenuItem
-    \li QPlatformSystemTrayIcon
-    \li platform palettes
-    \li platform fonts
-    \li theme hints
     \endlist
 \endlist
 
-\c{qtbase/src/platformsupport} contains several helper classes for implementing
-platform plugins on Unix-like systems.
+\note In addition to the QPA APIs, there are many other platform abstractions
+in Qt, for example the event dispatcher abstractions in \l{Qt Core}, the
+rendering hardware abstractions in RHI, and the multimedia backends in \l{Qt Multimedia}.
+The QPA APIs are mostly focused on window system integration and related support.
 
 \section1 QPA Plugins
 
-The following table summarizes the platform plugins available for QPA:
+Concrete implementations of the interfaces listed above live in QPA plugins,
+or platform plugins, adding support for the various platforms Qt runs on.
+QPA plugins are implemented by subclassing the \c QPlatform* classes.
+
+The following table summarizes the platform plugins available:
 
 \table
 \header
@@ -118,7 +111,7 @@ The following table summarizes the platform plugins available for QPA:
 \row
     \li \c qcocoa
     \li QCocoaIntegrationPlugin
-    \li \l{Qt for macOS}{Cocoa support}
+    \li \l{Qt for macOS}{macOS support}
 \row
     \li \c qdirect2d
     \li QWindowsDirect2DIntegrationPlugin
@@ -180,4 +173,21 @@ The following table summarizes the platform plugins available for QPA:
     \li QWebGLIntegrationPlugin
     \li \l{Qt Quick WebGL}{WebGL} support for Qt Quick applications
 \endtable
+
+\section2 Writing a QPA plugin
+
+There is no detailed tutorial documentation for writing QPA plugins at this
+time. However, there are two minimal plugins shipped with Qt for testing and
+other special purposes that you can use as examples:
+
+\list
+\li \c{qtbase/src/plugins/platforms/minimal/}
+\li \c{qtbase/src/plugins/platforms/minimalegl/}
+\endlist
+
+The \c qminimal plugin is used for tools that link against \l{Qt GUI}, but do
+not require window system integration (for example, \c qmlplugindump).
+It also has diagnostic support for dumping window contents to image files
+as determined by environment variables.
+
 */
diff --git a/doc/src/topics.qdoc b/doc/src/topics.qdoc
index 978abc24..25999b34 100644
--- a/doc/src/topics.qdoc
+++ b/doc/src/topics.qdoc
@@ -44,6 +44,7 @@ functionality and can be used as a starting point for learning how to to get the
 \li \l{Integrating Web Content}
 \li \l{Mobile APIs}
 \li \l{QML Applications}
+\li \l{Platform Integration}
 \endlist
 
 \list
diff --git a/qtdoc.pro b/qtdoc.pro
index bb9dc702..053031a9 100644
--- a/qtdoc.pro
+++ b/qtdoc.pro
@@ -5,5 +5,5 @@ cmake.file = doc/src/cmake/cmake.pro
 doc.file = doc/doc.pro
 doc.depends = cmake
 
-SUBDIRS += doc cmake
+SUBDIRS += doc cmake doc/src/platformintegration