--- a/src/ai/api/ai_list.hpp	Sat Apr 14 09:44:18 2007 +0000
+++ b/src/ai/api/ai_list.hpp	Sat Apr 14 09:48:23 2007 +0000
@@ -19,9 +19,9 @@
 	AIListSorter *sorter;
 
 public:
-	typedef std::set<int32> AIItemList;
-	typedef std::map<int32, AIItemList> AIListBucket;
-	typedef std::map<int32, int32> AIListMap;
+	typedef std::set<int32> AIItemList;               ///< The list of items inside the bucket
+	typedef std::map<int32, AIItemList> AIListBucket; ///< The bucket list per value
+	typedef std::map<int32, int32> AIListMap;         ///< List per item
 
 	AIListMap items;           ///< The items in the list
 	AIListBucket buckets;      ///< The items in the list, sorted by value
@@ -175,8 +175,13 @@
 	 * The definition how valuators should look.
 	 */
 	class Valuator {
+		/* Make this valuator a friend of AIList, so we can access the private.
+		 *  Nobody else should ever call Valuate. */
 		friend class AIList;
 	public:
+		/**
+		 * Virtual destructor, needed to make compilers happy.
+		 */
 		virtual ~Valuator() {}
 
 	private: