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: [PATCH] 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(-)

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 :*/