From 9d5171482ef6b6d27cf66a6b7480bb6de941885c Mon Sep 17 00:00:00 2001
From: "Ignacio R. Morelle" <shadowm@wesnoth.org>
Date: Fri, 4 Nov 2011 04:27:51 +0000
Subject: [PATCH] Describe the major caveat for display::find_button() in a
 doxygen comment

---
 src/display.hpp | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/src/display.hpp b/src/display.hpp
index c266abdf068..190c06ef712 100644
--- a/src/display.hpp
+++ b/src/display.hpp
@@ -272,6 +272,17 @@ public:
 	void clear_redraw_observers();
 
 	theme& get_theme() { return theme_; }
+
+	/**
+	 * Retrieves a pointer to a theme UI button.
+	 *
+	 * @note The returned pointer may either be NULL, meaning the button
+	 *       isn't defined by the current theme, or point to a valid
+	 *       gui::button object. However, the objects retrieved will be
+	 *       destroyed and recreated by draw() method calls. Do *NOT* store
+	 *       these pointers for longer than strictly necessary to
+	 *       accomplish a specific task before the next screen refresh.
+	 */
 	gui::button* find_button(const std::string& id);
 	gui::button::TYPE string_to_button_type(std::string type);
 	void create_buttons();