From 05212f5e44571945b40f72ae70ec7012af85fe75 Mon Sep 17 00:00:00 2001
From: Jari Vetoniemi <mailroxas@gmail.com>
Date: Thu, 10 Apr 2014 20:19:15 +0300
Subject: [PATCH] Improve documentation.

---
 lib/bemenu.h | 6 +++++-
 lib/menu.c   | 6 +++++-
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/lib/bemenu.h b/lib/bemenu.h
index 35a94e5..4534966 100644
--- a/lib/bemenu.h
+++ b/lib/bemenu.h
@@ -239,6 +239,8 @@ int bmMenuSetHighlighted(bmMenu *menu, bmItem *item);
 /**
  * Get highlighted item from bmMenu instance.
  *
+ * @warning The pointer returned by this function may be invalid after items change.
+ *
  * @param menu bmMenu instance from where to get highlighted item.
  * @return Selected bmItem instance, **NULL** if none highlighted.
  */
@@ -247,7 +249,7 @@ bmItem* bmMenuGetHighlightedItem(const bmMenu *menu);
 /**
  * Set selected items to bmMenu instance.
  *
- * @warning The list won't be copied.
+ * @warning The list won't be copied, do not free it.
  *
  * @param menu bmMenu instance where items will be set.
  * @param items Array of bmItem pointers to set.
@@ -259,6 +261,8 @@ int bmMenuSetSelectedItems(bmMenu *menu, bmItem **items, unsigned int nmemb);
 /**
  * Get selected items from bmMenu instance.
  *
+ * @warning The pointer returned by this function may be invalid after selection or items change.
+ *
  * @param menu bmMenu instance from where to get selected items.
  * @param outNmemb Reference to unsigned int where total count of returned items will be stored.
  * @return Pointer to array of bmItem pointers.
diff --git a/lib/menu.c b/lib/menu.c
index 5f57ae8..bf26c51 100644
--- a/lib/menu.c
+++ b/lib/menu.c
@@ -307,6 +307,8 @@ int bmMenuSetHighlighted(bmMenu *menu, bmItem *item)
 /**
  * Get highlighted item from bmMenu instance.
  *
+ * @warning The pointer returned by this function may be invalid after items change.
+ *
  * @param menu bmMenu instance from where to get highlighted item.
  * @return Selected bmItem instance, **NULL** if none highlighted.
  */
@@ -326,7 +328,7 @@ bmItem* bmMenuGetHighlightedItem(const bmMenu *menu)
 /**
  * Set selected items to bmMenu instance.
  *
- * @warning The list won't be copied.
+ * @warning The list won't be copied, do not free it.
  *
  * @param menu bmMenu instance where items will be set.
  * @param items Array of bmItem pointers to set.
@@ -342,6 +344,8 @@ int bmMenuSetSelectedItems(bmMenu *menu, bmItem **items, unsigned int nmemb)
 /**
  * Get selected items from bmMenu instance.
  *
+ * @warning The pointer returned by this function may be invalid after selection or items change.
+ *
  * @param menu bmMenu instance from where to get selected items.
  * @param outNmemb Reference to unsigned int where total count of returned items will be stored.
  * @return Pointer to array of bmItem pointers.