add doxygen comments to recall_list_manager.hpp

src/recall_list_manager.hpp

@@ -12,7 +12,7 @@
    See the COPYING file for more details.
 */
 
-// This class encapsulates the recall list of a team
+/// This class encapsulates the recall list of a team.
 
 #ifndef RECALL_LIST_MGR_HPP
 #define RECALL_LIST_MGR_HPP
@@ -31,38 +31,38 @@ class recall_list_manager {
 	typedef std::vector<UnitPtr >::iterator iterator;
 	typedef std::vector<UnitPtr >::const_iterator const_iterator;
 
-	iterator begin() { return recall_list_.begin();}
-	iterator end() { return recall_list_.end(); }
+	iterator begin() { return recall_list_.begin();} //!< begin iterator
+	iterator end() { return recall_list_.end(); } //!< end iterator
 
-	const_iterator begin() const { return recall_list_.begin();}
-	const_iterator end() const { return recall_list_.end(); }
+	const_iterator begin() const { return recall_list_.begin();} //!< begin const iterator
+	const_iterator end() const { return recall_list_.end(); } //!< end const iterator
 
-	UnitPtr operator[](size_t index) { return recall_list_[index]; }
-	UnitConstPtr operator[](size_t index) const { return recall_list_[index]; }
+	UnitPtr operator[](size_t index) { return recall_list_[index]; } //!< vector style dereference
+	UnitConstPtr operator[](size_t index) const { return recall_list_[index]; } //!< vector style dereference
 
-	UnitPtr find_if_matches_id(const std::string & unit_id);
-	UnitPtr extract_if_matches_id(const std::string & unit_id);
-	UnitConstPtr find_if_matches_id(const std::string & unit_id) const;
-	void erase_if_matches_id(const std::string & unit_id);
+	UnitPtr find_if_matches_id(const std::string & unit_id); //!< Find a unit by id. Null pointer if not found.
+	UnitPtr extract_if_matches_id(const std::string & unit_id); //!< Find a unit by id, and extract from this object if found. Null if not found.
+	UnitConstPtr find_if_matches_id(const std::string & unit_id) const; //!< Const find by id.
+	void erase_if_matches_id(const std::string & unit_id); //!< Erase any unit with this id.
 
-	UnitPtr find_if_matches_underlying_id(size_t uid);
-	UnitPtr extract_if_matches_underlying_id(size_t uid);
-	UnitConstPtr find_if_matches_underlying_id(size_t uid) const;
-	void erase_by_underlying_id(size_t uid);
+	UnitPtr find_if_matches_underlying_id(size_t uid); //!< Find a unit by underlying id. Null pointer if not found.
+	UnitPtr extract_if_matches_underlying_id(size_t uid); //!< Find a unit by underlying id, and extract if found. Null if not found.
+	UnitConstPtr find_if_matches_underlying_id(size_t uid) const; //!< Const find by underlying id.
+	void erase_by_underlying_id(size_t uid); //!< Erase any unit with this underlying id.
 
-	iterator erase_index(size_t index);
-	iterator erase(iterator it);
+	iterator erase_index(size_t index); //!< Erase by index.
+	iterator erase(iterator it); //!< Erase an iterator to this object.
 
-	size_t find_index(const std::string & unit_id) const;
-	size_t size() const { return recall_list_.size(); }
-	bool empty() const { return recall_list_.empty(); }
+	size_t find_index(const std::string & unit_id) const; //!< Find the index of a unit by its id.
+	size_t size() const { return recall_list_.size(); } //!< Get the number of units on the list.
+	bool empty() const { return recall_list_.empty(); } //!< Is it empty?
 
-	void add(const UnitPtr & ptr);
+	void add(const UnitPtr & ptr); //!< Add a unit to the list.
 
 private:
-	std::vector<UnitPtr > recall_list_;
+	std::vector<UnitPtr > recall_list_; //!< The underlying data struture. TODO: Should this be a map based on underlying id instead?
 
-	friend class ai::readonly_context_impl;
+	friend class ai::readonly_context_impl; //!< Friend AI module for ease of implementation there.
 };
 
 #endif