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 *?

1 files changed, 17 insertions, 4 deletions

diff --git a/pidgin/gtkutils.h b/pidgin/gtkutils.h
index ad23b36f1f..0751b7d7c7 100644
--- a/pidgin/gtkutils.h
+++ b/pidgin/gtkutils.h
@@ -600,13 +600,26 @@ char *pidgin_make_pretty_arrows(const char *str);
 
 /**
  * Creates a "mini-dialog" suitable for embedding in the buddy list scrollbook
- *
- * @param handle         A handle
- * @param stock_id       The ID of a stock image to use in the mini dialog
+ * with pidgin_blist_add_alert().
+ *
+ * @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,