[gtk+] Document that the drag icon window will be modified

[Matthias Clasen <matthiasc src gnome org>]

commit cfec3ba7949a2f0625e2ea01d9e0da76803ed54d
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Jul 11 18:09:47 2014 -0400

    Document that the drag icon window will be modified
    
    This is in response to the complaint in
    https://bugzilla.gnome.org/show_bug.cgi?id=732991

 gtk/gtkdnd.c |   17 +++++++++++------
 1 files changed, 11 insertions(+), 6 deletions(-)
---
diff --git a/gtk/gtkdnd.c b/gtk/gtkdnd.c
index 124ae74..7913b00 100644
--- a/gtk/gtkdnd.c
+++ b/gtk/gtkdnd.c
@@ -3206,15 +3206,20 @@ gtk_drag_set_icon_window (GdkDragContext *context,
  * gtk_drag_set_icon_widget: (method)
  * @context: the context for a drag. (This must be called 
           with a  context for the source side of a drag)
- * @widget: a toplevel window to use as an icon.
- * @hot_x: the X offset within @widget of the hotspot.
- * @hot_y: the Y offset within @widget of the hotspot.
+ * @widget: a toplevel window to use as an icon
+ * @hot_x: the X offset within @widget of the hotspot
+ * @hot_y: the Y offset within @widget of the hotspot
  * 
- * Changes the icon for a widget to a given widget. GTK+
- * will not destroy the icon, so if you don’t want
+ * Changes the icon for a widget to a given widget.
+ * GTK+ will not destroy the icon, so if you don’t want
  * it to persist, you should connect to the “drag-end” 
  * signal and destroy it yourself.
- **/
+ *
+ * GTK+ will, however, change the opacity and position of
+ * the window as part of the drag animation. If you want
+ * to reuse the window, you have to restore these to
+ * the values you need after each drag operation.
+ */
 void 
 gtk_drag_set_icon_widget (GdkDragContext    *context,
                          GtkWidget         *widget,