From 4a931c5ed4aaa0637bd9d41f7e45e9f22d9513ce Mon Sep 17 00:00:00 2001
From: Jari Vetoniemi <mailroxas@gmail.com>
Date: Thu, 10 Apr 2014 15:48:55 +0300
Subject: Nicer doxygen output

---
 doxygen/Mainpage.dox | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
 create mode 100644 doxygen/Mainpage.dox

(limited to 'doxygen/Mainpage.dox')

diff --git a/doxygen/Mainpage.dox b/doxygen/Mainpage.dox
new file mode 100644
index 0000000..8da4792
--- /dev/null
+++ b/doxygen/Mainpage.dox
@@ -0,0 +1,19 @@
+/**
+@mainpage Main Page
+
+bemenu is a dynamic menu library and client program inspired by dmenu.
+You can create flexible menu oriented programs using the library interface in your favorite language that has bemenu bindings avaialable.
+
+Unlike old dmenu approach, with library you don't have to feed unneccessary metadata into client program and parse the result.
+Instead your program will be aware of the items and possible metadata inside the menu.
+It's also possible to use multiple menus or dynamically remove/insert items.
+
+Features:
+   - Multiple layouts
+   - Different filtering algorithms:
+      - Vanilla dmenu filtering
+   - Rendering backends (UI toolkits are loaded dynamically, not depended):
+      - Curses
+
+bemenu also provides 'bemenu' executable that is compatible with dmenu interface.
+*/
-- 
cgit v1.2.3-70-g09d2


From 8631506d9d1522f1a24e528f75682201b4f3cc7b Mon Sep 17 00:00:00 2001
From: Jari Vetoniemi <mailroxas@gmail.com>
Date: Thu, 10 Apr 2014 17:26:42 +0300
Subject: Update documentation, include only public API in doxygen output.

---
 client/client.c      |  16 -------
 doxygen/Doxyfile.in  |   6 +--
 doxygen/Mainpage.dox |   2 +
 lib/bemenu.h         | 119 ++++++++++++++++++++++++++++++++++++++++-----------
 lib/filter.c         |  28 ++++++------
 lib/internal.h       |  13 +++---
 lib/item.c           |   8 ++--
 lib/menu.c           |  46 ++++++++++++--------
 lib/util.c           |  46 ++++++++++----------
 9 files changed, 172 insertions(+), 112 deletions(-)

(limited to 'doxygen/Mainpage.dox')

diff --git a/client/client.c b/client/client.c
index 973e57a..4419967 100644
--- a/client/client.c
+++ b/client/client.c
@@ -1,10 +1,3 @@
-/**
- * @file client.c
- *
- * Sample client using the libbemenu.
- * Also usable as dmenu replacement.
- */
-
 #include <stdlib.h>
 #include <stdio.h>
 #include <string.h>
@@ -86,15 +79,6 @@ static void readItemsToMenuFromStdin(bmMenu *menu)
         free(line);
 }
 
-/**
- * Main method
- *
- * This function gives and takes the life of our program.
- *
- * @param argc Number of arguments from command line
- * @param argv Pointer to array of the arguments
- * @return exit status of the program
- */
 int main(int argc, char **argv)
 {
     (void)argc, (void)argv;
diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in
index fcd3604..3b80187 100644
--- a/doxygen/Doxyfile.in
+++ b/doxygen/Doxyfile.in
@@ -90,7 +90,7 @@ OUTPUT_LANGUAGE        = English
 # documentation (similar to Javadoc). Set to NO to disable this.
 # The default value is: YES.
 
-BRIEF_MEMBER_DESC      = NO
+BRIEF_MEMBER_DESC      = YES
 
 # If the REPEAT_BRIEF tag is set to YES doxygen will prepend the brief
 # description of a member or function before the detailed description
@@ -765,7 +765,7 @@ INPUT_ENCODING         = UTF-8
 # *.md, *.mm, *.dox, *.py, *.f90, *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf,
 # *.qsf, *.as and *.js.
 
-FILE_PATTERNS          =
+FILE_PATTERNS          = *.h *.dox
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
 # be searched for input files as well.
@@ -796,7 +796,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       =
+EXCLUDE_PATTERNS       = internal.h
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
diff --git a/doxygen/Mainpage.dox b/doxygen/Mainpage.dox
index 8da4792..869071c 100644
--- a/doxygen/Mainpage.dox
+++ b/doxygen/Mainpage.dox
@@ -16,4 +16,6 @@ Features:
       - Curses
 
 bemenu also provides 'bemenu' executable that is compatible with dmenu interface.
+
+Get started on the <a href="modules.html">Modules</a> page.
 */
diff --git a/lib/bemenu.h b/lib/bemenu.h
index d8e604b..f2f0372 100644
--- a/lib/bemenu.h
+++ b/lib/bemenu.h
@@ -1,13 +1,34 @@
 /**
  * @file bemenu.h
  *
- * Public header
+ * Public API header.
  */
 
+typedef struct _bmMenu bmMenu;
+typedef struct _bmItem bmItem;
+
+/**
+ * @defgroup Menu
+ * @brief Menu container.
+ *
+ * Holds all the items, runs logic and gets rendered.
+ */
+
+/**
+ * @defgroup Item
+ * @brief Item container.
+ *
+ * Contains properties for visual representation of item.
+ */
+
+/**
+ * @addtogroup Menu
+ * @{ */
+
 /**
  * Draw mode constants for bmMenu instance draw mode.
  *
- * BM_DRAW_MODE_LAST is provided for enumerating draw modes.
+ * @link ::bmDrawMode BM_DRAW_MODE_LAST @endlink is provided for enumerating draw modes.
  * Instancing with it however provides exactly same functionality as BM_DRAW_MODE_NONE.
  */
 typedef enum bmDrawMode {
@@ -19,7 +40,7 @@ typedef enum bmDrawMode {
 /**
  * Filter mode constants for bmMenu instance filter mode.
  *
- * BM_FILTER_MODE_LAST is provided for enumerating filter modes.
+ * @link ::bmFilterMode BM_FILTER_MODE_LAST @endlink is provided for enumerating filter modes.
  * Using it as filter mode however provides exactly same functionality as BM_FILTER_MODE_DMENU.
  */
 typedef enum bmFilterMode {
@@ -31,9 +52,9 @@ typedef enum bmFilterMode {
 /**
  * Result constants from bmMenuRunWithKey function.
  *
- * BM_RUN_RESULT_RUNNING means that menu is running and thus should be still renderer && ran.
- * BM_RUN_RESULT_SELECTED means that menu was closed and items were selected.
- * BM_RUN_RESULT_CANCEL means that menu was closed and selection was canceled.
+ * - @link ::bmRunResult BM_RUN_RESULT_RUNNING @endlink means that menu is running and thus should be still renderer && ran.
+ * - @link ::bmRunResult BM_RUN_RESULT_SELECTED @endlink means that menu was closed and items were selected.
+ * - @link ::bmRunResult BM_RUN_RESULT_CANCEL @endlink means that menu was closed and selection was canceled.
  */
 typedef enum bmRunResult {
     BM_RUN_RESULT_RUNNING,
@@ -44,7 +65,7 @@ typedef enum bmRunResult {
 /**
  * Key constants.
  *
- * BM_KEY_LAST is provided for enumerating keys.
+ * @link ::bmKey BM_KEY_LAST @endlink is provided for enumerating keys.
  */
 typedef enum bmKey {
     BM_KEY_NONE,
@@ -68,14 +89,15 @@ typedef enum bmKey {
     BM_KEY_LAST
 } bmKey;
 
-typedef struct _bmMenu bmMenu;
-typedef struct _bmItem bmItem;
+/**
+ * @name Menu Memory
+ * @{ */
 
 /**
  * Create new bmMenu instance.
  *
  * @param drawMode Render method to be used for this menu instance.
- * @return bmMenu for new menu instance, NULL if creation failed.
+ * @return bmMenu for new menu instance, **NULL** if creation failed.
  */
 bmMenu* bmMenuNew(bmDrawMode drawMode);
 
@@ -93,6 +115,12 @@ void bmMenuFree(bmMenu *menu);
  */
 void bmMenuFreeItems(bmMenu *menu);
 
+/**  @} Menu Memory */
+
+/**
+ * @name Menu Properties
+ * @{ */
+
 /**
  * Set active filter mode to bmMenu instance.
  *
@@ -113,7 +141,7 @@ bmFilterMode bmMenuGetFilterMode(const bmMenu *menu);
  * Set title to bmMenu instance.
  *
  * @param menu bmMenu instance where to set title.
- * @param title C "string" to set as title, can be NULL for empty title.
+ * @param title C "string" to set as title, can be **NULL** for empty title.
  */
 int bmMenuSetTitle(bmMenu *menu, const char *title);
 
@@ -121,10 +149,16 @@ int bmMenuSetTitle(bmMenu *menu, const char *title);
  * Get title from bmMenu instance.
  *
  * @param menu bmMenu instance where to get title from.
- * @return Pointer to null terminated C "string", can be NULL for empty title.
+ * @return Pointer to null terminated C "string", can be **NULL** for empty title.
  */
 const char* bmMenuGetTitle(const bmMenu *menu);
 
+/**  @} Properties */
+
+/**
+ * @name Menu Items
+ * @{ */
+
 /**
  * Add item to bmMenu instance at specific index.
  *
@@ -147,6 +181,8 @@ int bmMenuAddItem(bmMenu *menu, bmItem *item);
 /**
  * Remove item from bmMenu instance at specific index.
  *
+ * @warning The item won't be freed, use bmItemFree to do that.
+ *
  * @param menu bmMenu instance from where item will be removed.
  * @param index Index of item to remove.
  * @return 1 on successful add, 0 on failure.
@@ -155,7 +191,8 @@ int bmMenuRemoveItemAt(bmMenu *menu, unsigned int index);
 
 /**
  * Remove item from bmMenu instance.
- * The item won't be freed, use bmItemFree to do that.
+ *
+ * @warning The item won't be freed, use bmItemFree to do that.
  *
  * @param menu bmMenu instance from where item will be removed.
  * @param item bmItem instance to remove.
@@ -167,18 +204,20 @@ int bmMenuRemoveItem(bmMenu *menu, bmItem *item);
  * Get selected item from bmMenu instance.
  *
  * @param menu bmMenu instance from where to get selected item.
- * @return Selected bmItem instance, NULL if none selected.
+ * @return Selected bmItem instance, **NULL** if none selected.
  */
 bmItem* bmMenuGetSelectedItem(const bmMenu *menu);
 
 /**
  * Get items from bmMenu instance.
  *
+ * @warning The pointer returned by this function may be invalid after removing or adding new items.
+ *
  * @param menu bmMenu instance from where to get items.
- * @param nmemb Reference to unsigned int where total count of returned items will be stored.
+ * @param outNmemb Reference to unsigned int where total count of returned items will be stored.
  * @return Pointer to array of bmItem pointers.
  */
-bmItem** bmMenuGetItems(const bmMenu *menu, unsigned int *nmemb);
+bmItem** bmMenuGetItems(const bmMenu *menu, unsigned int *outNmemb);
 
 /**
  * Get filtered (displayed) items from bmMenu instance.
@@ -187,16 +226,16 @@ bmItem** bmMenuGetItems(const bmMenu *menu, unsigned int *nmemb);
  *          Do not store this pointer.
  *
  * @param menu bmMenu instance from where to get filtered items.
- * @param nmemb Reference to unsigned int where total count of returned items will be stored.
+ * @param outNmemb Reference to unsigned int where total count of returned items will be stored.
  * @return Pointer to array of bmItem pointers.
  */
-bmItem** bmMenuGetFilteredItems(const bmMenu *menu, unsigned int *nmemb);
+bmItem** bmMenuGetFilteredItems(const bmMenu *menu, unsigned int *outNmemb);
 
 /**
  * Set items to bmMenu instance.
  * Will replace all the old items on bmMenu instance.
  *
- * If items is NULL, or nmemb is zero, all items will be freed from the menu.
+ * If items is **NULL**, or nmemb is zero, all items will be freed from the menu.
  *
  * @param menu bmMenu instance where items will be set.
  * @param items Array of bmItem pointers to set.
@@ -205,6 +244,12 @@ bmItem** bmMenuGetFilteredItems(const bmMenu *menu, unsigned int *nmemb);
  */
 int bmMenuSetItems(bmMenu *menu, const bmItem **items, unsigned int nmemb);
 
+/**  @} Menu Items */
+
+/**
+ * @name Menu Logic
+ * @{ */
+
 /**
  * Render bmMenu instance using chosen draw method.
  *
@@ -215,13 +260,13 @@ void bmMenuRender(const bmMenu *menu);
 /**
  * Poll key and unicode from underlying UI toolkit.
  *
- * This function will block on CURSES draw mode.
+ * This function will block on @link ::bmDrawMode BM_DRAW_MODE_CURSES @endlink draw mode.
  *
  * @param menu bmMenu instance from which to poll.
- * @param unicode Reference to unsigned int.
+ * @param outUnicode Reference to unsigned int.
  * @return bmKey for polled key.
  */
-bmKey bmMenuGetKey(bmMenu *menu, unsigned int *unicode);
+bmKey bmMenuGetKey(bmMenu *menu, unsigned int *outUnicode);
 
 /**
  * Advances menu logic with key and unicode as input.
@@ -233,11 +278,23 @@ bmKey bmMenuGetKey(bmMenu *menu, unsigned int *unicode);
  */
 bmRunResult bmMenuRunWithKey(bmMenu *menu, bmKey key, unsigned int unicode);
 
+/**  @} Menu Logic */
+
+/**  @} Menu */
+
+/**
+ * @addtogroup Item
+ * @{ */
+
+/**
+ * @name Item Memory
+ * @{ */
+
 /**
  * Allocate a new item.
  *
- * @param text Pointer to null terminated C "string", can be NULL for empty text.
- * @return bmItem for new item instance, NULL if creation failed.
+ * @param text Pointer to null terminated C "string", can be **NULL** for empty text.
+ * @return bmItem for new item instance, **NULL** if creation failed.
  */
 bmItem* bmItemNew(const char *text);
 
@@ -248,11 +305,17 @@ bmItem* bmItemNew(const char *text);
  */
 void bmItemFree(bmItem *item);
 
+/**  @} Item Memory */
+
+/**
+ * @name Item Properties
+ * @{ */
+
 /**
  * Set text to bmItem instance.
  *
  * @param item bmItem instance where to set text.
- * @param text C "string" to set as text, can be NULL for empty text.
+ * @param text C "string" to set as text, can be **NULL** for empty text.
  */
 int bmItemSetText(bmItem *item, const char *text);
 
@@ -260,8 +323,12 @@ int bmItemSetText(bmItem *item, const char *text);
  * Get text from bmItem instance.
  *
  * @param item bmItem instance where to get text from.
- * @return Pointer to null terminated C "string", can be NULL for empty text.
+ * @return Pointer to null terminated C "string", can be **NULL** for empty text.
  */
 const char* bmItemGetText(const bmItem *item);
 
+/**  @} Item Properties */
+
+/**  @} Item */
+
 /* vim: set ts=8 sw=4 tw=0 :*/
diff --git a/lib/filter.c b/lib/filter.c
index 92e5683..33126c0 100644
--- a/lib/filter.c
+++ b/lib/filter.c
@@ -7,16 +7,16 @@
  * Filter that mimics the vanilla dmenu filtering.
  *
  * @param menu bmMenu instance to filter.
- * @param count unsigned int reference to filtered items count.
- * @param selected unsigned int reference to new selected item index.
+ * @param outNmemb unsigned int reference to filtered items outNmemb.
+ * @param outSelected unsigned int reference to new outSelected item index.
  * @return Pointer to array of bmItem pointers.
  */
-bmItem** _bmFilterDmenu(bmMenu *menu, unsigned int *count, unsigned int *selected)
+bmItem** _bmFilterDmenu(bmMenu *menu, unsigned int *outNmemb, unsigned int *outSelected)
 {
     assert(menu);
-    assert(count);
-    assert(selected);
-    *count = *selected = 0;
+    assert(outNmemb);
+    assert(outSelected);
+    *outNmemb = *outSelected = 0;
 
     /* FIXME: not real dmenu like filtering at all */
 
@@ -29,28 +29,28 @@ bmItem** _bmFilterDmenu(bmMenu *menu, unsigned int *count, unsigned int *selecte
         bmItem *item = menu->items[i];
         if (item->text && strstr(item->text, menu->filter)) {
             if (f == 0 || item == bmMenuGetSelectedItem(menu))
-                *selected = f;
+                *outSelected = f;
             filtered[f++] = item;
         }
     }
 
-    return _bmShrinkItemList(&filtered, menu->itemsCount, (*count = f));
+    return _bmShrinkItemList(&filtered, menu->itemsCount, (*outNmemb = f));
 }
 
 /**
  * Filter that mimics the vanilla case-insensitive dmenu filtering.
  *
  * @param menu bmMenu instance to filter.
- * @param count unsigned int reference to filtered items count.
- * @param selected unsigned int reference to new selected item index.
+ * @param outNmemb unsigned int reference to filtered items outNmemb.
+ * @param outSelected unsigned int reference to new outSelected item index.
  * @return Pointer to array of bmItem pointers.
  */
-bmItem** _bmFilterDmenuCaseInsensitive(bmMenu *menu, unsigned int *count, unsigned int *selected)
+bmItem** _bmFilterDmenuCaseInsensitive(bmMenu *menu, unsigned int *outNmemb, unsigned int *outSelected)
 {
     assert(menu);
-    assert(count);
-    assert(selected);
-    *count = *selected = 0;
+    assert(outNmemb);
+    assert(outSelected);
+    *outNmemb = *outSelected = 0;
 
     /* FIXME: stub */
 
diff --git a/lib/internal.h b/lib/internal.h
index 41fb926..66eabbc 100644
--- a/lib/internal.h
+++ b/lib/internal.h
@@ -64,7 +64,6 @@ struct _bmMenu {
 
     /**
      * Text used to filter matches.
-     *
      * XXX: Change this to a pointer?
      */
     char filter[1024];
@@ -115,18 +114,18 @@ struct _bmMenu {
 int _bmDrawCursesInit(struct _bmRenderApi *api);
 
 /* filter.c */
-bmItem** _bmFilterDmenu(bmMenu *menu, unsigned int *count, unsigned int *selected);
-bmItem** _bmFilterDmenuCaseInsensitive(bmMenu *menu, unsigned int *count, unsigned int *selected);
+bmItem** _bmFilterDmenu(bmMenu *menu, unsigned int *outNmemb, unsigned int *outSelected);
+bmItem** _bmFilterDmenuCaseInsensitive(bmMenu *menu, unsigned int *outNmemb, unsigned int *outSelected);
 
 /* util.c */
 char* _bmStrdup(const char *s);
-bmItem** _bmShrinkItemList(bmItem ***list, size_t osize, size_t nsize);
+bmItem** _bmShrinkItemList(bmItem ***inOutList, size_t osize, size_t nsize);
 int _bmUtf8StringScreenWidth(const char *string);
 size_t _bmUtf8RuneNext(const char *string, size_t start);
 size_t _bmUtf8RunePrev(const char *string, size_t start);
 size_t _bmUtf8RuneWidth(const char *rune, unsigned int u8len);
-size_t _bmUtf8RuneRemove(char *string, size_t start, size_t *runeWidth);
-size_t _bmUtf8RuneInsert(char *string, size_t bufSize, size_t start, const char *rune, unsigned int u8len, size_t *runeWidth);
-size_t _bmUnicodeInsert(char *string, size_t bufSize, size_t start, unsigned int unicode, size_t *runeWidth);
+size_t _bmUtf8RuneRemove(char *string, size_t start, size_t *outRuneWidth);
+size_t _bmUtf8RuneInsert(char *string, size_t bufSize, size_t start, const char *rune, unsigned int u8len, size_t *outRuneWidth);
+size_t _bmUnicodeInsert(char *string, size_t bufSize, size_t start, unsigned int unicode, size_t *outRuneWidth);
 
 /* vim: set ts=8 sw=4 tw=0 :*/
diff --git a/lib/item.c b/lib/item.c
index 8320b9b..e6ccc7a 100644
--- a/lib/item.c
+++ b/lib/item.c
@@ -6,8 +6,8 @@
 /**
  * Allocate a new item.
  *
- * @param text Pointer to null terminated C "string", can be NULL for empty text.
- * @return bmItem instance.
+ * @param text Pointer to null terminated C "string", can be **NULL** for empty text.
+ * @return bmItem for new item instance, **NULL** if creation failed.
  */
 bmItem* bmItemNew(const char *text)
 {
@@ -39,7 +39,7 @@ void bmItemFree(bmItem *item)
  * Set text to bmItem instance.
  *
  * @param item bmItem instance where to set text.
- * @param text C "string" to set as text, can be NULL for empty text.
+ * @param text C "string" to set as text, can be **NULL** for empty text.
  */
 int bmItemSetText(bmItem *item, const char *text)
 {
@@ -60,7 +60,7 @@ int bmItemSetText(bmItem *item, const char *text)
  * Get text from bmItem instance.
  *
  * @param item bmItem instance where to get text from.
- * @return Pointer to null terminated C "string", can be NULL for empty text.
+ * @return Pointer to null terminated C "string", can be **NULL** for empty text.
  */
 const char* bmItemGetText(const bmItem *item)
 {
diff --git a/lib/menu.c b/lib/menu.c
index c8c6a26..3d41121 100644
--- a/lib/menu.c
+++ b/lib/menu.c
@@ -7,7 +7,7 @@
 /**
  * Filter function map.
  */
-static bmItem** (*filterFunc[BM_FILTER_MODE_LAST])(bmMenu *menu, unsigned int *count, unsigned int *selected) = {
+static bmItem** (*filterFunc[BM_FILTER_MODE_LAST])(bmMenu *menu, unsigned int *outNmemb, unsigned int *outSelected) = {
     _bmFilterDmenu, /* BM_FILTER_DMENU */
     _bmFilterDmenuCaseInsensitive /* BM_FILTER_DMENU_CASE_INSENSITIVE */
 };
@@ -53,7 +53,7 @@ static int _bmMenuGrowItems(bmMenu *menu)
  * Create new bmMenu instance.
  *
  * @param drawMode Render method to be used for this menu instance.
- * @return bmMenu for new menu instance, NULL if creation failed.
+ * @return bmMenu for new menu instance, **NULL** if creation failed.
  */
 bmMenu* bmMenuNew(bmDrawMode drawMode)
 {
@@ -155,7 +155,7 @@ bmFilterMode bmMenuGetFilterMode(const bmMenu *menu)
  * Set title to bmMenu instance.
  *
  * @param menu bmMenu instance where to set title.
- * @param title C "string" to set as title, can be NULL for empty title.
+ * @param title C "string" to set as title, can be **NULL** for empty title.
  */
 int bmMenuSetTitle(bmMenu *menu, const char *title)
 {
@@ -176,7 +176,7 @@ int bmMenuSetTitle(bmMenu *menu, const char *title)
  * Get title from bmMenu instance.
  *
  * @param menu bmMenu instance where to get title from.
- * @return Pointer to null terminated C "string", can be NULL for empty title.
+ * @return Pointer to null terminated C "string", can be **NULL** for empty title.
  */
 const char* bmMenuGetTitle(const bmMenu *menu)
 {
@@ -225,6 +225,8 @@ int bmMenuAddItem(bmMenu *menu, bmItem *item)
 /**
  * Remove item from bmMenu instance at specific index.
  *
+ * @warning The item won't be freed, use bmItemFree to do that.
+ *
  * @param menu bmMenu instance from where item will be removed.
  * @param index Index of item to remove.
  * @return 1 on successful add, 0 on failure.
@@ -244,6 +246,8 @@ int bmMenuRemoveItemAt(bmMenu *menu, unsigned int index)
 /**
  * Remove item from bmMenu instance.
  *
+ * @warning The item won't be freed, use bmItemFree to do that.
+ *
  * @param menu bmMenu instance from where item will be removed.
  * @param item bmItem instance to remove.
  * @return 1 on successful add, 0 on failure.
@@ -262,7 +266,7 @@ int bmMenuRemoveItem(bmMenu *menu, bmItem *item)
  * Get selected item from bmMenu instance.
  *
  * @param menu bmMenu instance from where to get selected item.
- * @return Selected bmItem instance, NULL if none selected.
+ * @return Selected bmItem instance, **NULL** if none selected.
  */
 bmItem* bmMenuGetSelectedItem(const bmMenu *menu)
 {
@@ -280,16 +284,18 @@ bmItem* bmMenuGetSelectedItem(const bmMenu *menu)
 /**
  * Get items from bmMenu instance.
  *
+ * @warning The pointer returned by this function may be invalid after removing or adding new items.
+ *
  * @param menu bmMenu instance from where to get items.
- * @param nmemb Reference to unsigned int where total count of returned items will be stored.
+ * @param outNmemb Reference to unsigned int where total count of returned items will be stored.
  * @return Pointer to array of bmItem pointers.
  */
-bmItem** bmMenuGetItems(const bmMenu *menu, unsigned int *nmemb)
+bmItem** bmMenuGetItems(const bmMenu *menu, unsigned int *outNmemb)
 {
     assert(menu);
 
-    if (nmemb)
-        *nmemb = menu->itemsCount;
+    if (outNmemb)
+        *outNmemb = menu->itemsCount;
 
     return menu->items;
 }
@@ -301,15 +307,15 @@ bmItem** bmMenuGetItems(const bmMenu *menu, unsigned int *nmemb)
  *          Do not store this pointer.
  *
  * @param menu bmMenu instance from where to get filtered items.
- * @param nmemb Reference to unsigned int where total count of returned items will be stored.
+ * @param outNmemb Reference to unsigned int where total count of returned items will be stored.
  * @return Pointer to array of bmItem pointers.
  */
-bmItem** bmMenuGetFilteredItems(const bmMenu *menu, unsigned int *nmemb)
+bmItem** bmMenuGetFilteredItems(const bmMenu *menu, unsigned int *outNmemb)
 {
     assert(menu);
 
-    if (nmemb)
-        *nmemb = (menu->filteredItems ? menu->filteredCount : menu->itemsCount);
+    if (outNmemb)
+        *outNmemb = (menu->filteredItems ? menu->filteredCount : menu->itemsCount);
 
     return (menu->filteredItems ? menu->filteredItems : menu->items);
 }
@@ -318,6 +324,8 @@ bmItem** bmMenuGetFilteredItems(const bmMenu *menu, unsigned int *nmemb)
  * Set items to bmMenu instance.
  * Will replace all the old items on bmMenu instance.
  *
+ * If items is **NULL**, or nmemb is zero, all items will be freed from the menu.
+ *
  * @param menu bmMenu instance where items will be set.
  * @param items Array of bmItem pointers to set.
  * @param nmemb Total count of items in array.
@@ -360,22 +368,22 @@ void bmMenuRender(const bmMenu *menu)
 /**
  * Poll key and unicode from underlying UI toolkit.
  *
- * This function will block on CURSES draw mode.
+ * This function will block on @link ::bmDrawMode BM_DRAW_MODE_CURSES @endlink draw mode.
  *
  * @param menu bmMenu instance from which to poll.
- * @param unicode Reference to unsigned int.
+ * @param outUnicode Reference to unsigned int.
  * @return bmKey for polled key.
  */
-bmKey bmMenuGetKey(bmMenu *menu, unsigned int *unicode)
+bmKey bmMenuGetKey(bmMenu *menu, unsigned int *outUnicode)
 {
     assert(menu);
-    assert(unicode);
+    assert(outUnicode);
 
-    *unicode = 0;
+    *outUnicode = 0;
     bmKey key = BM_KEY_NONE;
 
     if (menu->renderApi.getKey)
-        key = menu->renderApi.getKey(unicode);
+        key = menu->renderApi.getKey(outUnicode);
 
     return key;
 }
diff --git a/lib/util.c b/lib/util.c
index ae230c8..5eb980d 100644
--- a/lib/util.c
+++ b/lib/util.c
@@ -37,21 +37,21 @@ char* _bmStrdup(const char *string)
  * @param nsize New size the list will be shrinked to.
  * @return Pointer to list of bmItem pointers.
  */
-bmItem** _bmShrinkItemList(bmItem ***list, size_t osize, size_t nsize)
+bmItem** _bmShrinkItemList(bmItem ***inOutList, size_t osize, size_t nsize)
 {
-    assert(list);
+    assert(inOutList);
 
     if (nsize >= osize)
-        return *list;
+        return *inOutList;
 
     void *tmp = malloc(sizeof(bmItem*) * nsize);
     if (!tmp)
-        return *list;
+        return *inOutList;
 
-    memcpy(tmp, *list, sizeof(bmItem*) * nsize);
-    free(*list);
-    *list = tmp;
-    return *list;
+    memcpy(tmp, *inOutList, sizeof(bmItem*) * nsize);
+    free(*inOutList);
+    *inOutList = tmp;
+    return *inOutList;
 }
 
 /**
@@ -135,15 +135,15 @@ size_t _bmUtf8RuneWidth(const char *rune, unsigned int u8len)
  *
  * @param string Null terminated C "string".
  * @param start Start offset where to delete from. (cursor)
- * @param runeWidth Reference to size_t, return number of columns for removed rune, or -1 on failure.
+ * @param outRuneWidth Reference to size_t, return number of columns for removed rune, or -1 on failure.
  * @return Number of bytes removed from buffer.
  */
-size_t _bmUtf8RuneRemove(char *string, size_t start, size_t *runeWidth)
+size_t _bmUtf8RuneRemove(char *string, size_t start, size_t *outRuneWidth)
 {
     assert(string);
 
-    if (runeWidth)
-        *runeWidth = 0;
+    if (outRuneWidth)
+        *outRuneWidth = 0;
 
     size_t len = strlen(string), oldStart = start;
     if (len == 0 || len < start || !*string)
@@ -151,8 +151,8 @@ size_t _bmUtf8RuneRemove(char *string, size_t start, size_t *runeWidth)
 
     start -= _bmUtf8RunePrev(string, start);
 
-    if (runeWidth)
-        *runeWidth = _bmUtf8RuneWidth(string + start, oldStart - start);
+    if (outRuneWidth)
+        *outRuneWidth = _bmUtf8RuneWidth(string + start, oldStart - start);
 
     memmove(string + start, string + oldStart, len - oldStart);
     string[len - (oldStart - start)] = 0;
@@ -167,15 +167,15 @@ size_t _bmUtf8RuneRemove(char *string, size_t start, size_t *runeWidth)
  * @param start Start offset where to insert to. (cursor)
  * @param rune Buffer to insert to string.
  * @param u8len Byte length of the rune.
- * @param runeWidth Reference to size_t, return number of columns for inserted rune, or -1 on failure.
+ * @param outRuneWidth Reference to size_t, return number of columns for inserted rune, or -1 on failure.
  * @return Number of bytes inserted to buffer.
  */
-size_t _bmUtf8RuneInsert(char *string, size_t bufSize, size_t start, const char *rune, unsigned int u8len, size_t *runeWidth)
+size_t _bmUtf8RuneInsert(char *string, size_t bufSize, size_t start, const char *rune, unsigned int u8len, size_t *outRuneWidth)
 {
     assert(string);
 
-    if (runeWidth)
-        *runeWidth = 0;
+    if (outRuneWidth)
+        *outRuneWidth = 0;
 
     size_t len = strlen(string);
     if (len + u8len >= bufSize)
@@ -188,8 +188,8 @@ size_t _bmUtf8RuneInsert(char *string, size_t bufSize, size_t start, const char
     memmove(str + u8len, str, len - start);
     memcpy(str, rune, u8len);
 
-    if (runeWidth)
-        *runeWidth = _bmUtf8RuneWidth(rune, u8len);
+    if (outRuneWidth)
+        *outRuneWidth = _bmUtf8RuneWidth(rune, u8len);
     return u8len;
 }
 
@@ -200,10 +200,10 @@ size_t _bmUtf8RuneInsert(char *string, size_t bufSize, size_t start, const char
  * @param bufSize Size of the buffer.
  * @param start Start offset where to insert to. (cursor)
  * @param unicode Unicode character to insert.
- * @param runeWidth Reference to size_t, return number of columns for inserted rune, or -1 on failure.
+ * @param outRuneWidth Reference to size_t, return number of columns for inserted rune, or -1 on failure.
  * @return Number of bytes inserted to buffer.
  */
-size_t _bmUnicodeInsert(char *string, size_t bufSize, size_t start, unsigned int unicode, size_t *runeWidth)
+size_t _bmUnicodeInsert(char *string, size_t bufSize, size_t start, unsigned int unicode, size_t *outRuneWidth)
 {
     assert(string);
 
@@ -219,7 +219,7 @@ size_t _bmUnicodeInsert(char *string, size_t bufSize, size_t start, unsigned int
         mb[0] |= (unicode >> (i * 6 - 6));
     }
 
-    return _bmUtf8RuneInsert(string, bufSize, start, mb, u8len, runeWidth);
+    return _bmUtf8RuneInsert(string, bufSize, start, mb, u8len, outRuneWidth);
 }
 
 /* vim: set ts=8 sw=4 tw=0 :*/
-- 
cgit v1.2.3-70-g09d2


From 8e1ff89f9cedab9a5f5b5f6a702f76feda514182 Mon Sep 17 00:00:00 2001
From: Martin Langasek <martin.langasek@gmail.com>
Date: Sat, 12 Apr 2014 23:05:12 +0200
Subject: Fix typo in Mainpage.dox

---
 doxygen/Mainpage.dox | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doxygen/Mainpage.dox')

diff --git a/doxygen/Mainpage.dox b/doxygen/Mainpage.dox
index 869071c..1b91ebf 100644
--- a/doxygen/Mainpage.dox
+++ b/doxygen/Mainpage.dox
@@ -2,7 +2,7 @@
 @mainpage Main Page
 
 bemenu is a dynamic menu library and client program inspired by dmenu.
-You can create flexible menu oriented programs using the library interface in your favorite language that has bemenu bindings avaialable.
+You can create flexible menu oriented programs using the library interface in your favorite language that has bemenu bindings available.
 
 Unlike old dmenu approach, with library you don't have to feed unneccessary metadata into client program and parse the result.
 Instead your program will be aware of the items and possible metadata inside the menu.
-- 
cgit v1.2.3-70-g09d2