From a92bdcf02dc48d8314d282bec871a5ff8fcaefff Mon Sep 17 00:00:00 2001
From: Kalle Olavi Niemitalo <kon@iki.fi>
Date: Sat, 18 Jul 2009 19:37:29 +0300
Subject: [PATCH] Document add_dlg_button, add_dlg_ok_button

---
 src/bfu/button.h | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/src/bfu/button.h b/src/bfu/button.h
index ca7b3d65..a1a46cf5 100644
--- a/src/bfu/button.h
+++ b/src/bfu/button.h
@@ -28,6 +28,47 @@ struct widget_info_button {
 /* Define to find buttons without keyboard accelerator. */
 /* #define DEBUG_BUTTON_HOTKEY */
 
+/** @def add_dlg_ok_button
+ * Add a button that will close the dialog if pressed.
+ *
+ * void add_dlg_ok_button(struct dialog *dlg, unsigned char *text, int flags,
+ *                        ::done_handler_T *done, void *done_data);
+ *
+ * @param dlg
+ * The dialog in which the button is to be added.
+ *
+ * @param text
+ * Text displayed in the button.  This string should contain a
+ * keyboard accelerator, marked with a preceding '~'.  The pointer
+ * must remain valid as long as the dialog exists.
+ *
+ * @param flags
+ * Can be ::B_ENTER, ::B_ESC, or 0.
+ *
+ * @param done
+ * A function that BFU calls when the user presses this button.
+ * Before calling this, BFU checks the values of widgets.
+ * After the function returns, BFU closes the dialog.
+ *
+ * @param done_data
+ * A pointer to be passed to the @a done callback.  */
+
+/** @def add_dlg_button
+ * Add a button that need not close the dialog if pressed.
+ *
+ * void add_dlg_button(struct dialog *dlg, unsigned char *text, int flags,
+ *                     ::widget_handler_t *handler, void *data);
+ *
+ * @param handler
+ * A function that BFU calls when the user presses this button.
+ * BFU does not automatically check the values of widgets
+ * or close the dialog.
+ *
+ * @param data
+ * A pointer to any data needed by @a handler.  It does not get this
+ * pointer as a parameter but can read it from widget_data->widget->data.
+ *
+ * The other parameters are as in ::add_dlg_ok_button.  */
 
 #ifdef DEBUG_BUTTON_HOTKEY
 void add_dlg_button_do(const unsigned char *file, int line, struct dialog *dlg, unsigned char *text, int flags, widget_handler_T *handler, void *data, done_handler_T *done, void *done_data);