From c778475f2ae06b1d92b419a4494aeb863f581b51 Mon Sep 17 00:00:00 2001
From: Frederik Gladhorn <frederik.gladhorn@qt.io>
Date: Sun, 15 Sep 2019 20:59:45 +0200
Subject: [PATCH] Improve documentation

Summary:
Some of the documentation did not say what the purpose of the
respective class was, but rather gave a tautology.
For people new to the code base it helps to mention that
DPMS is power management.

That DataDevice is for copy-and-paste and drag-and-drop is
maybe obvious to people used to X11 API, but not very clear
to most others.

When first reading the KWayland code, some explanations
help getting around.

Reviewers: #kwin, romangg

Reviewed By: #kwin, romangg

Subscribers: romangg, zzag, kde-frameworks-devel

Tags: #frameworks

Differential Revision: https://phabricator.kde.org/D23915
---
 src/wayland/datadevice_interface.h |  7 ++++++-
 src/wayland/dpms_interface.h       | 11 ++++++-----
 2 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/src/wayland/datadevice_interface.h b/src/wayland/datadevice_interface.h
index 009f5fd0b2..ca12f3bef6 100644
--- a/src/wayland/datadevice_interface.h
+++ b/src/wayland/datadevice_interface.h
@@ -38,7 +38,12 @@ class SeatInterface;
 class SurfaceInterface;
 
 /**
- * @brief Represents the Resource for the wl_data_device interface.
+ * @brief DataDeviceInterface allows clients to share data by copy-and-paste and drag-and-drop.
+ *
+ * The data device is per seat.
+ * Copy-and-paste use the selection functions.
+ *
+ * Represents the Resource for the wl_data_device interface.
  *
  * @see SeatInterface
  * @see DataSourceInterface
diff --git a/src/wayland/dpms_interface.h b/src/wayland/dpms_interface.h
index 4d0875d114..79736f6caa 100644
--- a/src/wayland/dpms_interface.h
+++ b/src/wayland/dpms_interface.h
@@ -33,12 +33,13 @@ namespace Server
 class Display;
 
 /**
- * @brief Global for the org_kde_kwin_dpms_manager interface.
+ * @brief Global for server side Display Power Management Signaling interface.
  *
- * If the DpmsManagerInterface is created it allows a client to
- * query the Dpms state on a given OutputInterface and request
- * changes for it. The code interaction happens only via the
- * OutputInterface.
+ * A DpmsManagerInterface allows a client to query the DPMS state
+ * on a given OutputInterface and request changes to it.
+ * Server-side the interaction happens only via the OutputInterface,
+ * for clients the Dpms class provides the API.
+ * This global implements org_kde_kwin_dpms_manager.
  *
  * To create a DpmsManagerInterface use:
  * @code