diff --git a/src/units/types.hpp b/src/units/types.hpp
index e1cc61a03c5b..55511db7b7ad 100644
--- a/src/units/types.hpp
+++ b/src/units/types.hpp
@@ -69,9 +69,9 @@ class unit_type
 
 	/**
 	 * Validate the id argument.
-	 * Replaces invalid characters with underscores.
-	 * @param id the proposed id for a unit_type
-	 * @throw error if id starts with a space
+	 * Replaces invalid characters in the reference with underscores.
+	 * @param id The proposed id for a unit_type.
+	 * @throw error if id starts with a space.
 	 */
 	static void check_id(std::string& id);
 
@@ -105,8 +105,8 @@ class unit_type
 	void add_advancement(const unit_type &advance_to,int experience);
 
 	/** Get the advancement tree
-	 *  @return a set of ids of all unit_type objects that this unit_type can
-	 *  advance to
+	 *  @return A set of ids of all unit_type objects that this unit_type can
+	 *  directly or indirectly advance to.
 	 */
 	std::set<std::string> advancement_tree() const;