# HG changeset patch
# User Will Thompson <will.thompson@collabora.co.uk>
# Date 1193790731 0
# Node ID f02eaf4cc0322e2660199984bbd8298c64e75ff4
# Parent  e694942bbcfa17b98225a3d470d151e9c53585ee
Improve the documentation of pidgin_make_mini_dialog().

Is it okay to change its return type from void * to GtkWidget * in 2.3, since
that's what it returns, and you have to pass it to pidgin_blist_add_alert()
anyway which expects a GtkWidget *?

diff -r e694942bbcfa -r f02eaf4cc032 pidgin/gtkutils.h
--- a/pidgin/gtkutils.h	Tue Oct 30 23:46:59 2007 +0000
+++ b/pidgin/gtkutils.h	Wed Oct 31 00:32:11 2007 +0000
@@ -600,13 +600,26 @@
 
 /**
  * Creates a "mini-dialog" suitable for embedding in the buddy list scrollbook
+ * with pidgin_blist_add_alert().
  *
- * @param handle         A handle
- * @param stock_id       The ID of a stock image to use in the mini dialog
+ * @param handle         The #PurpleConnection to which this mini-dialog
+ *                       refers, or @c NULL if it does not refer to a
+ *                       connection.  If @a handle is supplied, the mini-dialog
+ *                       will be automatically removed and destroyed when the
+ *                       connection signs off.
+ * @param stock_id       The ID of a stock image to use in the mini dialog.
  * @param primary        The primary text
  * @param secondary      The secondary text
  * @param user_data      Data to pass to the callbacks
- * @param ...            a NULL-terminated list of button labels and callbacks
+ * @param ...            a <tt>NULL</tt>-terminated list of button labels
+ *                       (<tt>char *</tt>) and callbacks, which should take a
+ *                       <tt>void *</tt> argument, as which @a user_data will
+ *                       be passed.  (Strictly speaking a <tt>GtkButton *</tt>
+ *                       will be passed as the second argument, but it can
+ *                       safely be omitted.)
+ * @return               A <tt>GtkWidget *</tt> suitable for passing to
+ *                       pidgin_blist_add_alert().
+ * @see pidginstock.h
  */
 void *pidgin_make_mini_dialog(PurpleConnection *handle, const char* stock_id, 
 				const char *primary, const char *secondary,