[gtk+/gtk-3-20] Document window-icon related api as 'may not work'

[Matthias Clasen <matthiasc src gnome org>]

commit 626190e275cd39429876945f72648f3f917887d7
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Aug 24 14:43:58 2016 -0400

    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 c742127..55756ca 100644
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -10314,7 +10314,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)
@@ -10337,6 +10338,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 8245229..fe4e881 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -4615,7 +4615,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
@@ -4703,7 +4704,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
@@ -4754,8 +4756,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.
@@ -4868,7 +4871,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()