doc: Add documentation for cmake functions

This adds documentation for the cmake functions used to generate
binding code for protocol extensions. Since the Wayland Client
library did not have any documentation landing page, it also
adds that. This currently only links to the cmake function, but
it can be extended to include other APIs later if we add them.

Fixes: QTBUG-114147
Change-Id: I07d8dbe3bc32e5845482fe3e69ec6ba94897331b
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
(cherry picked from commit 50d2717f2d69388bca3df91f6be2d6a6c535947a)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

9 files changed, 176 insertions, 3 deletions

diff --git a/examples/wayland/custom-extension/doc/src/custom-extension.qdoc b/examples/wayland/custom-extension/doc/src/custom-extension.qdoc
index 1da68f5d6..7b2cb0802 100644
--- a/examples/wayland/custom-extension/doc/src/custom-extension.qdoc
+++ b/examples/wayland/custom-extension/doc/src/custom-extension.qdoc
@@ -50,8 +50,8 @@
  * becomes a call to a virtual function which can be implemented to provide the actual response.
  *
  * In order to have \c qtwaylandscanner run automatically as part of the build, we use the
- * CMake functions \c qt6_generate_wayland_protocol_server_sources() and
- * \c qt6_generate_wayland_protocol_client_sources() for generating the server-side and
+ * CMake functions \l{qt_generate_wayland_protocol_server_sources}{qt_generate_wayland_protocol_server_sources()} and
+ * \l{qt_generate_wayland_protocol_client_sources}{qt_generate_wayland_protocol_client_sources()} for generating the server-side and
  * client-side glue code, respectively. (When using \c qmake, the \c WAYLANDSERVERSOURCES and
  * \c WAYLANDCLIENTSOURCES variables achieve the same.)
  *
diff --git a/examples/wayland/custom-shell/doc/src/custom-shell.qdoc b/examples/wayland/custom-shell/doc/src/custom-shell.qdoc
index b4938c03e..ba0fd8bf7 100644
--- a/examples/wayland/custom-shell/doc/src/custom-shell.qdoc
+++ b/examples/wayland/custom-shell/doc/src/custom-shell.qdoc
@@ -38,6 +38,12 @@
  *   \li An event informing the client of the shell surface's current minimized state.
  * \endlist
  *
+ * In order to have \c qtwaylandscanner run automatically as part of the build, we use the
+ * CMake functions \l{qt_generate_wayland_protocol_server_sources}{qt_generate_wayland_protocol_server_sources()} and
+ * \l{qt_generate_wayland_protocol_client_sources}{qt_generate_wayland_protocol_client_sources()} for generating the server-side and
+ * client-side glue code, respectively. (When using \c qmake, the \c WAYLANDSERVERSOURCES and
+ * \c WAYLANDCLIENTSOURCES variables achieve the same.)
+ *
  * \section1 The Client Plugin
  *
  * In order for the shell integration to be discovered by a Qt client, we must reimplement
diff --git a/src/client/CMakeLists.txt b/src/client/CMakeLists.txt
index 6d986ce8b..4916af81e 100644
--- a/src/client/CMakeLists.txt
+++ b/src/client/CMakeLists.txt
@@ -163,5 +163,9 @@ qt_internal_extend_target(WaylandClient CONDITION QT_FEATURE_draganddrop
         qwaylanddnd.cpp qwaylanddnd_p.h
 )
 
+qt_internal_add_docs(WaylandClient
+    doc/qtwaylandclient.qdocconf
+)
+
 qt_record_extra_qt_main_tools_package_dependency(WaylandClient WaylandScannerTools "${PROJECT_VERSION}")
 qt_record_extra_qt_package_dependency(WaylandClient WaylandGlobalPrivate "${PROJECT_VERSION}")
diff --git a/src/client/doc/qtwaylandclient.qdocconf b/src/client/doc/qtwaylandclient.qdocconf
new file mode 100644
index 000000000..20ceaef02
--- /dev/null
+++ b/src/client/doc/qtwaylandclient.qdocconf
@@ -0,0 +1,31 @@
+include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
+include($QT_INSTALL_DOCS/config/exampleurl-qtwayland.qdocconf)
+
+project                                                     = QtWaylandClient
+description                                                 = Qt Wayland Client Reference Documentation
+version                                                     = $QT_VERSION
+
+qhp.projects                                                = QtWaylandClient
+
+qhp.QtWaylandClient.file                                    = qtwaylandclient.qhp
+qhp.QtWaylandClient.namespace                               = org.qt-project.QtWaylandClient.$QT_VERSION_TAG
+qhp.QtWaylandClient.virtualFolder                           = QtWaylandClient
+qhp.QtWaylandClient.indexTitle                              = Qt Wayland Client
+qhp.QtWaylandClient.indexRoot                               =
+
+depends += qtcore \
+           qtqml \
+           qtquick \
+           qtdoc \
+           qtcmake \
+           qtwaylandcompositor
+
+headerdirs += \
+    ../
+sourcedirs += \
+    ../
+
+navigation.landingpage    = "Qt Wayland Client"
+
+# Enforce zero documentation warnings
+warninglimit = 0
diff --git a/src/client/doc/src/cmake/qt_generate_wayland_protocol_client_sources.qdoc b/src/client/doc/src/cmake/qt_generate_wayland_protocol_client_sources.qdoc
new file mode 100644
index 000000000..97a7f7ed4
--- /dev/null
+++ b/src/client/doc/src/cmake/qt_generate_wayland_protocol_client_sources.qdoc
@@ -0,0 +1,45 @@
+// Copyright (C) 2024 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+\page qt-generate-wayland-protocol-client-sources.html
+\ingroup cmake-commands-qtwaylandclient
+
+\title qt_generate_wayland_protocol_client_sources
+\keyword qt6_generate_wayland_protocol_client_sources
+
+\summary {Generates client-side C++ bindings for a Wayland protocol .XML file}
+
+\cmakecommandsince 6.0
+
+The command is defined in the \c WaylandClient component of the \c Qt6 package, which
+can be loaded like so:
+
+\badcode
+find_package(Qt6 REQUIRED COMPONENTS WaylandClient)
+\endcode
+
+\section1 Synopsis
+
+\badcode
+qt_generate_wayland_protocol_client_sources(target
+                                            FILES file1.xml [file2.xml ...])
+\endcode
+
+\versionlessCMakeCommandsNote qt6_generate_wayland_protocol_client_sources()
+
+\section1 Description
+
+qt_generate_wayland_protocol_client_sources() creates the build steps to run \c{waylandscanner} and
+\c{qtwaylandscanner} on one or more Wayland protocol files. The tools will in turn generate binding
+code in C and C++ for implementing the protocols, and the resulting files will be built as part
+of the \c target.
+
+qt_generate_wayland_protocol_client_sources() will trigger generation of the files needed to
+implement the client side of the protocol. \l{qt_generate_wayland_protocol_server_sources}{qt_generate_wayland_protocol_server_sources()}
+is the equivalent function for the compositor.
+
+See the \l{Custom Shell} or \l{Custom Extension} examples for a demonstration of how to use these
+functions.
+*/
+
diff --git a/src/client/doc/src/qtwaylandclient-overview.qdoc b/src/client/doc/src/qtwaylandclient-overview.qdoc
new file mode 100644
index 000000000..a6f5ce56a
--- /dev/null
+++ b/src/client/doc/src/qtwaylandclient-overview.qdoc
@@ -0,0 +1,36 @@
+// Copyright (C) 2024 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+  \page qtwaylandclient-index.html
+  \title Qt Wayland Client
+  \brief Library to enable connecting to a Wayland compositor as a client
+
+  The Qt Wayland Client library provides the necessary functions for an application to act
+  as a \l {https://wayland.freedesktop.org/}{Wayland} client and connect to a Wayland compositor.
+  For most use cases, the library is used automatically through the Wayland QPA plugin, and there is
+  no need for the application itself to use any functions from the library.
+
+  However, when paired with \l{Qt Wayland Compositor}, the cmake function
+  \l{qt_generate_wayland_protocol_client_sources}{qt_generate_wayland_protocol_client_sources()}
+  can be used to create custom protocol extensions.
+
+  \section1 Licenses and Attributions
+
+  Qt Wayland Compositor and the Qt Wayland integration plugin
+  are available under commercial licenses from \l{The Qt Company}.
+
+  In addition, Qt Wayland Compositor is available under the
+  \l{GNU General Public License, version 3}, while
+  the Qt Wayland integration plugin is available under the
+  \l{GNU Lesser General Public License, version 3} or the
+  \l{GNU General Public License, version 2}.
+
+  See \l{Qt Licensing} for further details.
+
+  Qt Wayland Compositor and the Qt Wayland integration plugin
+  use protocol definitions under following permissive licenses:
+
+  \generatelist{groupsbymodule attributions-qtwaylandcompositor}
+
+*/
diff --git a/src/compositor/doc/qtwaylandcompositor.qdocconf b/src/compositor/doc/qtwaylandcompositor.qdocconf
index f83ceb72f..fae83583f 100644
--- a/src/compositor/doc/qtwaylandcompositor.qdocconf
+++ b/src/compositor/doc/qtwaylandcompositor.qdocconf
@@ -39,7 +39,8 @@ depends += qtcore \
            qtwidgets \
            qtvirtualkeyboard \
            qtcmake \
-           qtopengl
+           qtopengl \
+           qtwaylandclient
 
 exampledirs += ../../../examples/wayland
 headerdirs += \
diff --git a/src/compositor/doc/src/cmake/qt_generate_wayland_protocol_server_sources.qdoc b/src/compositor/doc/src/cmake/qt_generate_wayland_protocol_server_sources.qdoc
new file mode 100644
index 000000000..5a5849463
--- /dev/null
+++ b/src/compositor/doc/src/cmake/qt_generate_wayland_protocol_server_sources.qdoc
@@ -0,0 +1,47 @@
+// Copyright (C) 2024 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+\page qt-generate-wayland-protocol-server-sources.html
+\ingroup cmake-commands-qtwaylandcompositor
+
+\title qt_generate_wayland_protocol_server_sources
+\keyword qt6_generate_wayland_protocol_server_sources
+
+\summary {Generates server-side C++ bindings for a Wayland protocol .XML file}
+
+\cmakecommandsince 6.0
+
+The command is defined in the \c WaylandCompositor component of the \c Qt6 package, which
+can be loaded like so:
+
+\badcode
+find_package(Qt6 REQUIRED COMPONENTS WaylandCompositor)
+\endcode
+
+\section1 Synopsis
+
+\badcode
+qt_generate_wayland_protocol_server_sources(target
+                                            FILES file1.xml [file2.xml ...])
+\endcode
+
+\versionlessCMakeCommandsNote qt6_generate_wayland_protocol_server_sources()
+
+\section1 Description
+
+qt_generate_wayland_protocol_server_sources() creates the build steps to run \c{waylandscanner} and
+\c{qtwaylandscanner} on one or more Wayland protocol files. The tools will in turn generate binding
+code in C and C++ for implementing the protocols, and the resulting files will be built as part
+of the \c target.
+
+qt_generate_wayland_protocol_server_sources() will trigger generation of the files needed to
+implement the compositor side of the protocol.
+
+\l{qt_generate_wayland_protocol_client_sources}{qt_generate_wayland_protocol_client_sources()}
+is the equivalent function for the client.
+
+See the \l{Custom Shell} or \l{Custom Extension} examples for a demonstration of how to use these
+functions.
+*/
+
diff --git a/src/compositor/doc/src/qtwaylandcompositor-overview.qdoc b/src/compositor/doc/src/qtwaylandcompositor-overview.qdoc
index 90933cd47..86d15a5fd 100644
--- a/src/compositor/doc/src/qtwaylandcompositor-overview.qdoc
+++ b/src/compositor/doc/src/qtwaylandcompositor-overview.qdoc
@@ -141,6 +141,9 @@
     \li \l{Qt Wayland Compositor C++ Classes}
   \endlist
 
+  In addition, the module provides the CMake function
+  \l{qt_generate_wayland_protocol_server_sources}{qt_generate_wayland_protocol_server_sources()}.
+
   \section1 Module Evolution
   \l{Porting to Qt 6 - Qt Wayland Compositor} lists important changes in the
   module API and functionality that were done for the Qt 6 series of Qt.