From 6c8eaaef2d011d6f98fbcf9f8b436aea1579f1e3 Mon Sep 17 00:00:00 2001
From: emersion <contact@emersion.fr>
Date: Fri, 8 Feb 2019 23:43:59 +0100
Subject: [PATCH] Deprecate old protocols

---
 include/wlr/types/wlr_gtk_primary_selection.h | 8 ++++++++
 include/wlr/types/wlr_screenshooter.h         | 8 ++++++++
 include/wlr/types/wlr_server_decoration.h     | 8 ++++++++
 include/wlr/types/wlr_wl_shell.h              | 8 ++++++++
 include/wlr/types/wlr_xdg_shell_v6.h          | 9 +++++++++
 5 files changed, 41 insertions(+)

diff --git a/include/wlr/types/wlr_gtk_primary_selection.h b/include/wlr/types/wlr_gtk_primary_selection.h
index 4d7f84af..f1a9a83b 100644
--- a/include/wlr/types/wlr_gtk_primary_selection.h
+++ b/include/wlr/types/wlr_gtk_primary_selection.h
@@ -1,3 +1,8 @@
+/*
+ * This protocol is obsolete and will be removed in a future version. The
+ * recommended replacement is wp-primary-selection.
+ */
+
 /*
  * This an unstable interface of wlroots. No guarantees are made regarding the
  * future consistency of this API.
@@ -12,6 +17,9 @@
 #include <wayland-server.h>
 #include <wlr/types/wlr_seat.h>
 
+/**
+ * A primary selection manager which implements the GTK protocol.
+ */
 struct wlr_gtk_primary_selection_device_manager {
 	struct wl_global *global;
 	struct wl_list resources; // wl_resource_get_link
diff --git a/include/wlr/types/wlr_screenshooter.h b/include/wlr/types/wlr_screenshooter.h
index b7b87b39..d90ed5e1 100644
--- a/include/wlr/types/wlr_screenshooter.h
+++ b/include/wlr/types/wlr_screenshooter.h
@@ -1,3 +1,8 @@
+/*
+ * This protocol is obsolete and will be removed in a future version. The
+ * recommended replacement is wlr-screencopy.
+ */
+
 /*
  * This an unstable interface of wlroots. No guarantees are made regarding the
  * future consistency of this API.
@@ -11,6 +16,9 @@
 
 #include <wayland-server.h>
 
+/**
+ * A very basic screenshooter interrface which implements the Orbital protocol.
+ */
 struct wlr_screenshooter {
 	struct wl_global *global;
 	struct wl_list screenshots; // wlr_screenshot::link
diff --git a/include/wlr/types/wlr_server_decoration.h b/include/wlr/types/wlr_server_decoration.h
index ff8d1369..3e4eb5e1 100644
--- a/include/wlr/types/wlr_server_decoration.h
+++ b/include/wlr/types/wlr_server_decoration.h
@@ -1,3 +1,8 @@
+/*
+ * This protocol is obsolete and will be removed in a future version. The
+ * recommended replacement is xdg-decoration.
+ */
+
 /*
  * This an unstable interface of wlroots. No guarantees are made regarding the
  * future consistency of this API.
@@ -34,6 +39,9 @@ enum wlr_server_decoration_manager_mode {
 	WLR_SERVER_DECORATION_MANAGER_MODE_SERVER = 2,
 };
 
+/**
+ * A decoration negociation interface which implements the KDE protocol.
+ */
 struct wlr_server_decoration_manager {
 	struct wl_global *global;
 	struct wl_list resources;
diff --git a/include/wlr/types/wlr_wl_shell.h b/include/wlr/types/wlr_wl_shell.h
index dffbb4d7..67abc1b3 100644
--- a/include/wlr/types/wlr_wl_shell.h
+++ b/include/wlr/types/wlr_wl_shell.h
@@ -1,3 +1,8 @@
+/*
+ * This protocol is obsolete and will be removed in a future version. The
+ * recommended replacement is xdg-shell.
+ */
+
 /*
  * This an unstable interface of wlroots. No guarantees are made regarding the
  * future consistency of this API.
@@ -13,6 +18,9 @@
 #include <wayland-server.h>
 #include <wlr/types/wlr_seat.h>
 
+/**
+ * A very basic interface to provide desktop-style user interfaces.
+ */
 struct wlr_wl_shell {
 	struct wl_global *global;
 	struct wl_list resources;
diff --git a/include/wlr/types/wlr_xdg_shell_v6.h b/include/wlr/types/wlr_xdg_shell_v6.h
index a69e488f..b3ea72e0 100644
--- a/include/wlr/types/wlr_xdg_shell_v6.h
+++ b/include/wlr/types/wlr_xdg_shell_v6.h
@@ -1,3 +1,8 @@
+/*
+ * This protocol is obsolete and will be removed in a future version. The
+ * recommended replacement is xdg-shell.
+ */
+
 /*
  * This an unstable interface of wlroots. No guarantees are made regarding the
  * future consistency of this API.
@@ -14,6 +19,10 @@
 #include <wlr/types/wlr_seat.h>
 #include "xdg-shell-unstable-v6-protocol.h"
 
+/**
+ * An interface enabling clients to turn their wl_surfaces into windows in a
+ * desktop environment.
+ */
 struct wlr_xdg_shell_v6 {
 	struct wl_global *global;
 	struct wl_list clients;