From f66a76d99846d34f861bd7d5253b9f0b3486f3cb Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Wed, 24 Aug 2016 14:43:58 -0400
Subject: [PATCH] Document window-icon related api as 'may not work'

Some platforms simply don't have window icons (such as Wayland).
---
 gdk/gdkwindow.c |  5 ++++-
 gtk/gtkwindow.c | 13 ++++++++-----
 2 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index be40ec5a14..514732d818 100644
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -10642,7 +10642,8 @@ gdk_window_get_event_compression (GdkWindow *window)
  * image quality since the window manager may only need to scale the
  * icon by a small amount or not at all.
  *
- **/
+ * Note that some platforms don't support window icons.
+ */
 void
 gdk_window_set_icon_list (GdkWindow *window,
 			  GList     *pixbufs)
@@ -10665,6 +10666,8 @@ gdk_window_set_icon_list (GdkWindow *window,
  *
  * Using %NULL for @name unsets the icon title; further calls to
  * gdk_window_set_title() will again update the icon title as well.
+ *
+ * Note that some platforms don't support window icons.
  **/
 void
 gdk_window_set_icon_name (GdkWindow   *window,
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 4c9346a3e0..725f9e055e 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -4638,7 +4638,8 @@ gtk_window_unrealize_icon (GtkWindow *window)
  * Sets up the icon representing a #GtkWindow. The icon is used when
  * the window is minimized (also known as iconified).  Some window
  * managers or desktop environments may also place it in the window
- * frame, or display it in other contexts.
+ * frame, or display it in other contexts. On others, the icon is not
+ * used at all, so your mileage may vary.
  *
  * gtk_window_set_icon_list() allows you to pass in the same icon in
  * several hand-drawn sizes. The list should contain the natural sizes
@@ -4726,7 +4727,8 @@ gtk_window_get_icon_list (GtkWindow  *window)
  * Sets up the icon representing a #GtkWindow. This icon is used when
  * the window is minimized (also known as iconified).  Some window
  * managers or desktop environments may also place it in the window
- * frame, or display it in other contexts.
+ * frame, or display it in other contexts. On others, the icon is not
+ * used at all, so your mileage may vary.
  *
  * The icon should be provided in whatever size it was naturally
  * drawn; that is, don’t scale the image before passing it to
@@ -4777,8 +4779,9 @@ update_themed_icon (GtkWindow *window)
  * @window: a #GtkWindow
  * @name: (allow-none): the name of the themed icon
  *
- * Sets the icon for the window from a named themed icon. See
- * the docs for #GtkIconTheme for more details.
+ * Sets the icon for the window from a named themed icon.
+ * See the docs for #GtkIconTheme for more details.
+ * On some platforms, the window icon is not used at all.
  *
  * Note that this has nothing to do with the WM_ICON_NAME 
  * property which is mentioned in the ICCCM.
@@ -4891,7 +4894,7 @@ load_pixbuf_verbosely (const char *filename,
  * @filename: (type filename): location of icon file
  * @err: (allow-none): location to store error, or %NULL.
  *
- * Sets the icon for @window.  
+ * Sets the icon for @window.
  * Warns on failure if @err is %NULL.
  *
  * This function is equivalent to calling gtk_window_set_icon()