Whiteboard: Comments

src/whiteboard/highlight_visitor.hpp

@@ -32,7 +32,10 @@ static lg::log_domain log_whiteboard_highlight("whiteboard/highlight");
 namespace wb
 {
 
-
+/**
+ * Visitor that handles highlighting planned actions as you hover over them,
+ * and determine the right target for contextual execution.
+ */
 class highlight_visitor: public wb::visitor
 {
 public:
@@ -50,8 +53,10 @@ public:
 	action_ptr get_bump_target();
 	unit* get_selection_target();
 
+	/// @return the action the currently receives the highlight focus
 	weak_action_ptr get_main_highlight() { return main_highlight_; }
 	typedef std::deque<weak_action_ptr> secondary_highlights_t;
+	/// @return the collection of actions that are highlighted but don't have the focus
 	secondary_highlights_t get_secondary_highlights() { return secondary_highlights_; }
 
 

src/whiteboard/manager.hpp

@@ -40,7 +40,7 @@ class mapbuilder_visitor;
 class highlight_visitor;
 
 /**
- * This class holds and manages all of the whiteboard's planned actions.
+ * This class is the frontend of the whiteboard framework for the rest of the Wesnoth code.
  */
 class manager : private boost::noncopyable
 {

src/whiteboard/side_actions.hpp

@@ -32,6 +32,11 @@ namespace wb
 
 class move;
 
+/**
+ * This internal whiteboard class holds the planned action queue for a team, and offers many
+ * utility methods to create and manipulate them. It maintains an internal data structure
+ * but mostly hides it by providing its own iterators, begin() and end() methods, etc.
+ */
 class side_actions: public boost::enable_shared_from_this<side_actions>
 {
 public:

src/whiteboard/validate_visitor.hpp

@@ -26,6 +26,10 @@
 namespace wb
 {
 
+/**
+ * Visits all the actions in the given side_actions, building a future unit map as it goes,
+ * and checking the validity of each action.
+ */
 class validate_visitor: public mapbuilder_visitor
 {
 public: