From b94424635eeb73783ba43a1b501b95ea40ad8c92 Mon Sep 17 00:00:00 2001
From: Richard Russon <rich@flatcap.org>
Date: Thu, 27 Sep 2018 00:01:30 +0100
Subject: [PATCH] menu: document api functions

---
 menu.h | 60 +++++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 41 insertions(+), 19 deletions(-)

diff --git a/menu.h b/menu.h
index 643f8e3eb..346eb4cb7 100644
--- a/menu.h
+++ b/menu.h
@@ -80,28 +80,50 @@ struct Menu
   char *prompt;  /**< prompt for user, similar to mutt_multi_choice */
   char *keys;    /**< keys used in the prompt */
 
-  /* callback to generate an index line for the requested element */
-  void (*menu_make_entry)(char *buf, size_t buflen, struct Menu *menu, int num);
-
-  /* how to search the menu */
-  int (*menu_search)(struct Menu *, regex_t *re, int n);
-
-  int (*menu_tag)(struct Menu *, int i, int m);
-
-  /* these are used for custom redrawing callbacks */
-  void (*menu_custom_redraw)(struct Menu *);
-  void *redraw_data;
-
-  /* color pair to be used for the requested element
-   * (default function returns ColorDefs[MT_COLOR_NORMAL])
-   */
-  int (*menu_color)(int i);
-
   /* the following are used only by mutt_menu_loop() */
   int top;        /**< entry that is the top of the current page */
-  int oldcurrent; /**< for driver use only. */
-  int search_dir;  /**< direction of search */
+  int oldcurrent; /**< for driver use only */
+  int search_dir; /**< direction of search */
   int tagged;     /**< number of tagged entries */
+
+  /**
+   * menu_make_entry - Format a item for a menu
+   * @param[out] buf    Buffer in which to save string
+   * @param[in]  buflen Buffer length
+   * @param[in]  menu   Menu containing items
+   * @param[in]  line   Menu line number
+   */
+  void (*menu_make_entry)   (char *buf, size_t buflen, struct Menu *menu, int line);
+  /**
+   * menu_search - Search a menu for a item matching a regex
+   * @param menu Menu to search
+   * @param rx   Regex to match
+   * @param line Menu entry to match
+   * @retval  0 Success
+   * @retval >0 Error, e.g. REG_NOMATCH
+   */
+  int  (*menu_search)       (struct Menu *menu, regex_t *rx, int line);
+  /**
+   * menu_tag - Tag some menu items
+   * @param menu Menu to tag
+   * @param sel  Current selection
+   * @param act  Action: 0 untag, 1 tag, -1 toggle
+   * @retval num Net change in number of tagged attachments
+   */
+  int  (*menu_tag)          (struct Menu *menu, int sel, int act);
+  /**
+   * menu_color - Calculate the colour for a line of the menu
+   * @param line Menu line number
+   * @retval >0 Colour pair in an integer
+   * @retval  0 No colour
+   */
+  int  (*menu_color)        (int line);
+  /**
+   * menu_custom_redraw - Redraw the menu
+   * @param menu Menu to redraw
+   */
+  void (*menu_custom_redraw)(struct Menu *menu);
+  void *redraw_data;
 };
 
 void         menu_bottom_page(struct Menu *menu);
-- 
2.40.0