add doxygen comments to unit_animation_component.hpp

src/unit_animation_component.hpp

@@ -36,6 +36,7 @@ class unit_animation_component
 		STATE_FORGET,     /** animation will be automatically replaced by a standing anim when finished */
 		STATE_ANIM};      /** normal anims */
 
+	/** Default construct a unit animation component corresponding to a unit. */
 	unit_animation_component(unit & my_unit) : 
 		u_(my_unit),
 		anim_(NULL),
@@ -47,6 +48,7 @@ class unit_animation_component
 		refreshing_(false),
 		unit_halo_(halo::NO_HALO) {}
 
+	/** Copy construct a unit animation component, for use when copy constructing a unit. */
 	unit_animation_component(unit & my_unit, const unit_animation_component & o) : 
 		u_(my_unit),
 		anim_(NULL),
@@ -58,6 +60,7 @@ class unit_animation_component
 		refreshing_(o.refreshing_),
 		unit_halo_(halo::NO_HALO) {}
 
+	/** Chooses an appropriate animation from the list of known animations. */
 	const unit_animation* choose_animation(const display& disp,
 		       	const map_location& loc, const std::string& event,
 		       	const map_location& second_loc = map_location::null_location(),
@@ -66,47 +69,61 @@ class unit_animation_component
 			const attack_type* attack=NULL,const attack_type* second_attack = NULL,
 			int swing_num =0);
 
+	/** Sets the animation state to standing. */
 	void set_standing(bool with_bars = true);
 
+	/** Sets the animation state to ghosted. (For use with whiteboard / planning mode.) */
 	void set_ghosted(bool with_bars = true);
+
+	/** Whiteboard related somehow. TODO: Figure out exactly what this does. */
 	void set_disabled_ghosted(bool with_bars = true);
 
+	/** Sets the animation state to idling. */
 	void set_idling();
+
+	/** Sets the animation state to that when the unit is selected */
 	void set_selecting();
 
+	/** Begin an animation. */
 	void start_animation (int start_time, const unit_animation *animation,
 		bool with_bars,  const std::string &text = "",
 		Uint32 text_color = 0, STATE state = STATE_ANIM);
 
+	/** Invalidates an animation with respect to a display object, preparing it for redraw. */
 	bool invalidate(const display & disp);
 
+	/** Intermittently activates the idling animations in place of the standing animations. Used by display object. */
 	void refresh();
 
+	/** Clear the haloes associated to the unit */
 	void clear_haloes();
 
+	/** Resets the animations list after the unit is advanced. */
 	void reset_after_advance(const unit_type * newtype = NULL);
 
+	/** Adds an animation described by a config. Uses an internal cache to avoid redoing work. */
 	void apply_new_animation_effect(const config & effect);
 
+	/** Get a pointer to the current animation. */
 	unit_animation* get_animation() const { return anim_.get(); }
 
 	friend class unit;
 	friend class unit_drawer;
 private:
-	const unit & u_;
+	const unit & u_; /**< A reference to the unit that owns this object. It does so with a scoped pointer, so this reference should not dangle. */
 
-	boost::scoped_ptr<unit_animation> anim_;
-	std::vector<unit_animation> animations_;
+	boost::scoped_ptr<unit_animation> anim_; /**< The current animation. */
+	std::vector<unit_animation> animations_; /**< List of registered animations for this unit. */
 
-	STATE state_; //animation state
+	STATE state_; //!< animation state
 
-	int next_idling_;      // used for animation
-	int frame_begin_time_; // used for animation
+	int next_idling_;      //!< time for next idle animation
+	int frame_begin_time_; //!< time for the frame to begin
 
-	bool draw_bars_;
-	bool refreshing_; // avoid infinite recursion. flag used for drawing / animation
+	bool draw_bars_;  //!< bool indicating whether to draw bars with the unit 
+	bool refreshing_; //!< avoid infinite recursion. flag used for drawing / animation
 
-	int unit_halo_; // flag used for drawing / animation
+	int unit_halo_; //!< flag used for drawing / animation
 };
 
 #endif