# HG changeset patch
# User truebrain
# Date 1204050755 0
# Node ID 38560cd27070d14a7620a0782f15e11f4b200b08
# Parent  053e53a1650ec5e771145d38658ba6e946d0d344
(svn r12273) [NoAI] -Documentation: big change of many list-related comments. It is now more readable, more explaining, and all unneeded things (API-wise) are removed

diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_abstractlist.hpp
--- a/src/ai/api/ai_abstractlist.hpp	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_abstractlist.hpp	Tue Feb 26 18:32:35 2008 +0000
@@ -235,7 +235,18 @@
 		virtual ~Valuator() {}
 
 	private:
+		/**
+		 * The Valuator. This function is called for every entry in the List it is
+		 *  used on. Input is always int32 and output is always int32, but it can
+		 *  be casted from TownID, IndustryID, ...
+		 */
 		virtual int32 Valuate(int32 item) const = 0;
+
+		/**
+		 * To ensure Valuators are only used on Lists they are ment to used on,
+		 *  this value contains the name of the List they should be used on.
+		 * @note a possible value is NULL, to indicate it can be used on any list.
+		 */
 		virtual const char *GetListName() const = 0;
 	};
 
@@ -248,6 +259,8 @@
 private:
 	/**
 	 * The name of the list, to check if a Valuator can be used on this list.
+	 * @note a possible value is NULL, to indicate all valuators can be used on
+	 *  this list.
 	 */
 	virtual const char *GetListName() const { return NULL; };
 };
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_enginelist.cpp
--- a/src/ai/api/ai_enginelist.cpp	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_enginelist.cpp	Tue Feb 26 18:32:35 2008 +0000
@@ -1,10 +1,10 @@
 #include "ai_enginelist.hpp"
 #include "../../engine.h"
 
-AIEngineList::AIEngineList(AIVehicle::VehicleType type)
+AIEngineList::AIEngineList(AIVehicle::VehicleType vehicle_type)
 {
 	EngineID e;
-	FOR_ALL_ENGINEIDS_OF_TYPE(e, (::VehicleType)type) {
+	FOR_ALL_ENGINEIDS_OF_TYPE(e, (::VehicleType)vehicle_type) {
 		this->AddItem(e);
 	}
 }
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_enginelist.hpp
--- a/src/ai/api/ai_enginelist.hpp	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_enginelist.hpp	Tue Feb 26 18:32:35 2008 +0000
@@ -1,6 +1,7 @@
 /* $Id$ */
 
 /** @file ai_enginelist.hpp list all the engines */
+/** @defgroup AIEngineList AIEngineList - Valuators and lists working on/with AIEngineList */
 
 #ifndef AI_ENGINELIST_HPP
 #define AI_ENGINELIST_HPP
@@ -9,24 +10,19 @@
 #include "ai_vehicle.hpp"
 
 /**
- * Class that creates a list of engines.
+ * Create a list of engines based on a vehicle type.
+ * @ingroup AIEngineList
  */
 class AIEngineList : public AIAbstractList {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIEngineList"; }
 
 	/**
-	 * The constructor to make a list of engines.
+	 * @param vehicle_type The type of vehicle to make a list of engines for.
 	 */
-	AIEngineList(AIVehicle::VehicleType type);
+	AIEngineList(AIVehicle::VehicleType vehicle_type);
 
 private:
-	/**
-	 * The name of this list, to check if a Valuator can be used on this list.
-	 */
 	const char *GetListName() const { return "AIEngineList"; }
 };
 
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_enginelist.hpp.sq
--- a/src/ai/api/ai_enginelist.hpp.sq	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_enginelist.hpp.sq	Tue Feb 26 18:32:35 2008 +0000
@@ -12,7 +12,7 @@
 void SQAIEngineList_Register(Squirrel *engine) {
 	DefSQClass <AIEngineList> SQAIEngineList("AIEngineList");
 	SQAIEngineList.PreRegister(engine, "AIAbstractList");
-	SQAIEngineList.AddConstructor<void (AIEngineList::*)(AIVehicle::VehicleType type), 2>(engine, "xi");
+	SQAIEngineList.AddConstructor<void (AIEngineList::*)(AIVehicle::VehicleType vehicle_type), 2>(engine, "xi");
 
 	SQAIEngineList.DefSQStaticMethod(engine, &AIEngineList::GetClassName, "GetClassName", 1, "x");
 
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_enginelist_valuator.cpp
--- a/src/ai/api/ai_enginelist_valuator.cpp	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_enginelist_valuator.cpp	Tue Feb 26 18:32:35 2008 +0000
@@ -1,27 +1,27 @@
 #include "ai_enginelist_valuator.hpp"
 #include "ai_engine.hpp"
 
-int32 AIEngineList_vCargoType::Valuate(int32 engine) const
+int32 AIEngineList_vCargoType::Valuate(int32 engine_id) const
 {
-	return AIEngine::GetCargoType(engine);
-}
-
-int32 AIEngineList_vCapacity::Valuate(int32 engine) const
-{
-	return AIEngine::GetCapacity(engine);
+	return AIEngine::GetCargoType(engine_id);
 }
 
-int32 AIEngineList_vReliability::Valuate(int32 engine) const
+int32 AIEngineList_vCapacity::Valuate(int32 engine_id) const
 {
-	return AIEngine::GetReliability(engine);
+	return AIEngine::GetCapacity(engine_id);
 }
 
-int32 AIEngineList_vMaxSpeed::Valuate(int32 engine) const
+int32 AIEngineList_vReliability::Valuate(int32 engine_id) const
 {
-	return AIEngine::GetMaxSpeed(engine);
+	return AIEngine::GetReliability(engine_id);
 }
 
-int32 AIEngineList_vPrice::Valuate(int32 engine) const
+int32 AIEngineList_vMaxSpeed::Valuate(int32 engine_id) const
 {
-	return AIEngine::GetPrice(engine);
+	return AIEngine::GetMaxSpeed(engine_id);
 }
+
+int32 AIEngineList_vPrice::Valuate(int32 engine_id) const
+{
+	return AIEngine::GetPrice(engine_id);
+}
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_enginelist_valuator.hpp
--- a/src/ai/api/ai_enginelist_valuator.hpp	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_enginelist_valuator.hpp	Tue Feb 26 18:32:35 2008 +0000
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file ai_enginelist_valuator.hpp all the valuators for enginelist */
+/** @file ai_enginelist_valuator.hpp all the valuators for AIEngineList */
 
 #ifndef AI_ENGINELIST_VALUATOR_HPP
 #define AI_ENGINELIST_VALUATOR_HPP
@@ -9,107 +9,77 @@
 
 /**
  * Get the cargo-type for entries in an AIEngineList instance.
- * @note resulting items are of the type CargoID
- * @note the input items are of the type EngineID
+ * @note Resulting items are of the type CargoID.
+ * @note Can only operate on an AIEngineList instance.
+ * @ingroup AIEngineList
  */
 class AIEngineList_vCargoType : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIEngineList_vCargoType"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIEngineList"; }
-
-	int32 Valuate(int32 engine) const;
+	int32 Valuate(int32 engine_id) const;
 };
 
 /**
  * Get the capacity for entries in an AIEngineList instance.
- * @note resulting items are of the type int32
- * @note the input items are of the type EngineID
+ * @note Resulting items are of the type int32.
+ * @note Can only operate on an AIEngineList instance.
+ * @ingroup AIEngineList
  */
 class AIEngineList_vCapacity : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIEngineList_vCapacity"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIEngineList"; }
-
-	int32 Valuate(int32 engine) const;
+	int32 Valuate(int32 engine_id) const;
 };
 
 /**
  * Get the reliability for entries in an AIEngineList instance.
- * @note resulting items are of the type int32
- * @note the input items are of the type EngineID
+ * @note Resulting items are of the type int32.
+ * @note Can only operate on an AIEngineList instance.
+ * @ingroup AIEngineList
  */
 class AIEngineList_vReliability : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIEngineList_vReliability"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIEngineList"; }
-
-	int32 Valuate(int32 engine) const;
+	int32 Valuate(int32 engine_id) const;
 };
 
 /**
  * Get the max speed for entries in an AIEngineList instance.
- * @note resulting items are of the type int32
- * @note the input items are of the type EngineID
+ * @note Resulting items are of the type int32.
+ * @note Can only operate on an AIEngineList instance.
+ * @ingroup AIEngineList
  */
 class AIEngineList_vMaxSpeed : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIEngineList_vMaxSpeed"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIEngineList"; }
-
-	int32 Valuate(int32 engine) const;
+	int32 Valuate(int32 engine_id) const;
 };
 
 /**
  * Get the price for entries in an AIEngineList instance.
- * @note resulting items are of the type int32
- * @note the input items are of the type EngineID
+ * @note Resulting items are of the type int32.
+ * @note Can only operate on an AIEngineList instance.
+ * @ingroup AIEngineList
  */
 class AIEngineList_vPrice : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIEngineList_vPrice"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIEngineList"; }
-
-	int32 Valuate(int32 engine) const;
+	int32 Valuate(int32 engine_id) const;
 };
 
 #endif /* AI_ENGINELIST_VALUATOR_HPP */
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_industrylist.hpp
--- a/src/ai/api/ai_industrylist.hpp	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_industrylist.hpp	Tue Feb 26 18:32:35 2008 +0000
@@ -1,6 +1,7 @@
 /* $Id$ */
 
 /** @file ai_industrylist.hpp list all the industries */
+/** @defgroup AIIndustryList AIIndustryList - Valuators and lists working on/with AIIndustryList */
 
 #ifndef AI_INDUSTRYLIST_HPP
 #define AI_INDUSTRYLIST_HPP
@@ -8,70 +9,49 @@
 #include "ai_abstractlist.hpp"
 
 /**
- * Class that creates a list of current industries.
+ * Creates a list of industries that are currently on the map.
+ * @ingroup AIIndustryList
  */
 class AIIndustryList : public AIAbstractList {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIIndustryList"; }
-
-	/**
-	 * The constructor to make a list of industries.
-	 */
 	AIIndustryList();
 
 private:
-	/**
-	 * The name of this list, to check if a Valuator can be used on this list.
-	 */
 	const char *GetListName() const { return "AIIndustryList"; }
 };
 
 /**
- * Class that creates a list of industries which accept a given cargo.
+ * Creates a list of industries that accepts a given cargo.
+ * @ingroup AIIndustryList
  */
 class AIIndustryList_CargoAccepting : public AIAbstractList {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIIndustryList_CargoAccepting"; }
 
 	/**
-	 * The constructor to make a list of industries which accept a given cargo.
-	 * @param cargo_id the cargo this industry should accept.
+	 * @param cargo_id The cargo this industry should accept.
 	 */
 	AIIndustryList_CargoAccepting(CargoID cargo_id);
 
 private:
-	/**
-	 * The name of this list, to check if a Valuator can be used on this list.
-	 */
 	const char *GetListName() const { return "AIIndustryList"; }
 };
 
 /**
- * Class that creates a list of industries which produces a given cargo.
+ * Creates a list of industries that produce a given cargo.
+ * @ingroup AIIndustryList
  */
 class AIIndustryList_CargoProducing : public AIAbstractList {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIIndustryList_CargoProducing"; }
 
 	/**
-	 * The constructor to make a list of industries which produces a given cargo.
-	 * @param cargo_id the cargo this industry should produce.
+	 * @param cargo_id The cargo this industry should produce.
 	 */
 	AIIndustryList_CargoProducing(CargoID cargo_id);
 
 private:
-	/**
-	 * The name of this list, to check if a Valuator can be used on this list.
-	 */
 	const char *GetListName() const { return "AIIndustryList"; }
 };
 
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_industrylist_valuator.cpp
--- a/src/ai/api/ai_industrylist_valuator.cpp	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_industrylist_valuator.cpp	Tue Feb 26 18:32:35 2008 +0000
@@ -2,27 +2,27 @@
 #include "ai_industry.hpp"
 #include "ai_map.hpp"
 
-int32 AIIndustryList_vProduction::Valuate(int32 industry) const
+int32 AIIndustryList_vProduction::Valuate(int32 industry_id) const
 {
-	return AIIndustry::GetProduction(industry, this->cargo_type);
-}
-
-int32 AIIndustryList_vCargoAccepted::Valuate(int32 industry) const
-{
-	return AIIndustry::IsCargoAccepted(industry, this->cargo_type);
+	return AIIndustry::GetProduction(industry_id, this->cargo_id);
 }
 
-int32 AIIndustryList_vLocation::Valuate(int32 industry) const
+int32 AIIndustryList_vCargoAccepted::Valuate(int32 industry_id) const
 {
-	return AIIndustry::GetLocation(industry);
+	return AIIndustry::IsCargoAccepted(industry_id, this->cargo_id);
 }
 
-int32 AIIndustryList_vDistanceManhattanToTile::Valuate(int32 industry) const
+int32 AIIndustryList_vLocation::Valuate(int32 industry_id) const
 {
-	return AIMap::DistanceManhattan(this->tile, AIIndustry::GetLocation(industry));
+	return AIIndustry::GetLocation(industry_id);
 }
 
-int32 AIIndustryList_vDistanceSquareToTile::Valuate(int32 industry) const
+int32 AIIndustryList_vDistanceManhattanToTile::Valuate(int32 industry_id) const
 {
-	return AIMap::DistanceSquare(this->tile, AIIndustry::GetLocation(industry));
+	return AIMap::DistanceManhattan(this->tile, AIIndustry::GetLocation(industry_id));
 }
+
+int32 AIIndustryList_vDistanceSquareToTile::Valuate(int32 industry_id) const
+{
+	return AIMap::DistanceSquare(this->tile, AIIndustry::GetLocation(industry_id));
+}
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_industrylist_valuator.hpp
--- a/src/ai/api/ai_industrylist_valuator.hpp	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_industrylist_valuator.hpp	Tue Feb 26 18:32:35 2008 +0000
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file ai_industrylist_valuator.hpp all the valuators for industrylist */
+/** @file ai_industrylist_valuator.hpp all the valuators for AIIndustryList */
 
 #ifndef AI_INDUSTRYLIST_VALUATOR_HPP
 #define AI_INDUSTRYLIST_VALUATOR_HPP
@@ -8,135 +8,114 @@
 #include "ai_abstractlist.hpp"
 
 /**
- * Get the production of the cargo for entries in an AIIndustryList instance.
- * @note resulting items are of the type int32
- * @note the input items are of the type IndustryID
+ * Get the production rate of the cargo for entries in an AIIndustryList
+ *  instance. This is the amount of production you can expect in a month.
+ * @note Resulting items are of the type int32.
+ * @note Can only operate on an AIIndustryList instance.
+ * @ingroup AIIndustryList
  */
 class AIIndustryList_vProduction : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIIndustryList_vProduction"; }
 
 	/**
-	 * Custom constructor, we want a cargo-type as parameter.
+	 * @param cargo_id The cargo to check the production rate of.
 	 */
-	AIIndustryList_vProduction(CargoID cargo_type) { this->cargo_type = cargo_type; }
+	AIIndustryList_vProduction(CargoID cargo_id) :
+		cargo_id(cargo_id)
+	{}
 
 private:
-	CargoID cargo_type;
+	CargoID cargo_id;
 
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIIndustryList"; }
-
 	int32 Valuate(int32 industry) const;
 };
 
 /**
- * See which entries in the AIIndustryList instance accepts a certain cargo.
- * @note resulting items are of the type bool
- * @note the input items are of the type IndustryID
+ * See which entries in the AIIndustryList instance accepts a given cargo.
+ * @note Resulting items are of the type bool.
+ * @note Can only operate on an AIIndustryList instance.
+ * @ingroup AIIndustryList
  */
 class AIIndustryList_vCargoAccepted : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIIndustryList_vCargoAccepted"; }
 
 	/**
-	 * Custom constructor, we want a cargo-type as parameter.
+	 * @param cargo_id Check if this cargo is accepted.
 	 */
-	AIIndustryList_vCargoAccepted(CargoID cargo_type) { this->cargo_type = cargo_type; }
+	AIIndustryList_vCargoAccepted(CargoID cargo_id) :
+		cargo_id(cargo_id)
+	{}
 
 private:
-	CargoID cargo_type;
+	CargoID cargo_id;
 
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIIndustryList"; }
-
 	int32 Valuate(int32 industry) const;
 };
 
 /**
  * Get the location for entries in an AIIndustryList instance.
- * @note resulting items are of the type TileIndex
- * @note the input items are of the type IndustryID
+ * @note Resulting items are of the type TileIndex.
+ * @note Can only operate on an AIIndustryList instance.
+ * @ingroup AIIndustryList
  */
 class AIIndustryList_vLocation : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIIndustryList_vGetLocation"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIIndustryList"; }
-
 	int32 Valuate(int32 industry) const;
 };
 
 /**
  * Get the manhattan distance to a tile for entries in an AIIndustryList instance.
- * @note resulting items are of the type distance
- * @note the input items are of the type TileIndex
+ * @note Resulting items are of the type uint32.
+ * @note Can only operate on an AIIndustryList instance.
+ * @ingroup AIIndustryList
  */
 class AIIndustryList_vDistanceManhattanToTile : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIIndustryList_vDistanceManhattanToTile"; }
 
 	/**
-	 * Custom constructor, we want a tile as parameter.
+	 * @param tile The tile to get the distance to.
 	 */
-	AIIndustryList_vDistanceManhattanToTile(TileIndex tile) { this->tile = tile; }
+	AIIndustryList_vDistanceManhattanToTile(TileIndex tile) :
+		tile(tile)
+	{}
 
 private:
 	TileIndex tile;
 
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIIndustryList"; }
-
 	int32 Valuate(int32 station) const;
 };
 
 /**
  * Get the sqsuare distance to a tile for entries in an AIIndustryList instance.
- * @note resulting items are of the type distance
- * @note the input items are of the type TileIndex
+ * @note Resulting items are of the type uint32.
+ * @note Can only operate on an AIIndustryList instance.
+ * @ingroup AIIndustryList
  */
 class AIIndustryList_vDistanceSquareToTile : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIIndustryList_vDistanceSquareToTile"; }
 
 	/**
-	 * Custom constructor, we want a tile as parameter.
+	 * @param tile The tile to get the distance to.
 	 */
-	AIIndustryList_vDistanceSquareToTile(TileIndex tile) { this->tile = tile; }
+	AIIndustryList_vDistanceSquareToTile(TileIndex tile) :
+		tile(tile)
+	{}
 
 private:
 	TileIndex tile;
 
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIIndustryList"; }
-
 	int32 Valuate(int32 station) const;
 };
 
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_industrylist_valuator.hpp.sq
--- a/src/ai/api/ai_industrylist_valuator.hpp.sq	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_industrylist_valuator.hpp.sq	Tue Feb 26 18:32:35 2008 +0000
@@ -12,7 +12,7 @@
 void SQAIIndustryList_vProduction_Register(Squirrel *engine) {
 	DefSQClass <AIIndustryList_vProduction> SQAIIndustryList_vProduction("AIIndustryList_vProduction");
 	SQAIIndustryList_vProduction.PreRegister(engine);
-	SQAIIndustryList_vProduction.AddConstructor<void (AIIndustryList_vProduction::*)(CargoID cargo_type), 2>(engine, "xi");
+	SQAIIndustryList_vProduction.AddConstructor<void (AIIndustryList_vProduction::*)(CargoID cargo_id), 2>(engine, "xi");
 
 	SQAIIndustryList_vProduction.DefSQStaticMethod(engine, &AIIndustryList_vProduction::GetClassName, "GetClassName", 1, "x");
 
@@ -31,7 +31,7 @@
 void SQAIIndustryList_vCargoAccepted_Register(Squirrel *engine) {
 	DefSQClass <AIIndustryList_vCargoAccepted> SQAIIndustryList_vCargoAccepted("AIIndustryList_vCargoAccepted");
 	SQAIIndustryList_vCargoAccepted.PreRegister(engine);
-	SQAIIndustryList_vCargoAccepted.AddConstructor<void (AIIndustryList_vCargoAccepted::*)(CargoID cargo_type), 2>(engine, "xi");
+	SQAIIndustryList_vCargoAccepted.AddConstructor<void (AIIndustryList_vCargoAccepted::*)(CargoID cargo_id), 2>(engine, "xi");
 
 	SQAIIndustryList_vCargoAccepted.DefSQStaticMethod(engine, &AIIndustryList_vCargoAccepted::GetClassName, "GetClassName", 1, "x");
 
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_list.hpp
--- a/src/ai/api/ai_list.hpp	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_list.hpp	Tue Feb 26 18:32:35 2008 +0000
@@ -1,6 +1,7 @@
 /* $Id$ */
 
 /** @file ai_list.hpp a simple list which you can manipulate */
+/** @defgroup AIList AIList - Valuators and lists working on/with AIList */
 
 #ifndef AI_LIST_HPP
 #define AI_LIST_HPP
@@ -8,19 +9,14 @@
 #include "ai_abstractlist.hpp"
 
 /**
- * Class that creates a simple empty list of integers which you can manipulate.
+ * Creates an empty list, in which you can add integers.
+ * @ingroup AIList
  */
 class AIList : public AIAbstractList {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIList"; }
 
 private:
-	/**
-	 * The name of this list, to check if a Valuator can be used on this list.
-	 */
 	const char *GetListName() const { return "AIList"; }
 
 public:
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_list_valuator.hpp
--- a/src/ai/api/ai_list_valuator.hpp	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_list_valuator.hpp	Tue Feb 26 18:32:35 2008 +0000
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file ai_list_valuator.hpp all the valuators for list */
+/** @file ai_list_valuator.hpp all the valuators for AIList */
 
 #ifndef AI_LIST_VALUATOR_HPP
 #define AI_LIST_VALUATOR_HPP
@@ -8,23 +8,17 @@
 #include "ai_abstractlist.hpp"
 
 /**
- * Give a random value for the entries in an AIList instance.
- * @note resulting items are of the type int32
- * @note the input items are of the type int32
+ * Give a random value for each entry in an AIList instance.
+ * @note Resulting items are of the type int32.
+ * @note Can only operate on an AIList instance.
+ * @ingroup AIList
  */
 class AIList_vRandomize : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIList_vRandomize"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return NULL; }
-
 	int32 Valuate(int32 item) const;
 };
 
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_stationlist.cpp
--- a/src/ai/api/ai_stationlist.cpp	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_stationlist.cpp	Tue Feb 26 18:32:35 2008 +0000
@@ -7,11 +7,11 @@
 #include "../../order.h"
 #include "../../vehicle_base.h"
 
-AIStationList::AIStationList(AIStation::StationType type)
+AIStationList::AIStationList(AIStation::StationType station_type)
 {
 	Station *st;
 	FOR_ALL_STATIONS(st) {
-		if (st->owner == _current_player && (type == AIStation::STATION_ANY || (st->facilities & type) != 0)) this->AddItem(st->index);
+		if (st->owner == _current_player && (station_type == AIStation::STATION_ANY || (st->facilities & station_type) != 0)) this->AddItem(st->index);
 	}
 }
 
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_stationlist.hpp
--- a/src/ai/api/ai_stationlist.hpp	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_stationlist.hpp	Tue Feb 26 18:32:35 2008 +0000
@@ -1,6 +1,7 @@
 /* $Id$ */
 
 /** @file ai_stationlist.hpp list all the stations (you own) */
+/** @defgroup AIStationList AIStationList - Valuators and lists working on/with AIStationList */
 
 #ifndef AI_STATIONLIST_HPP
 #define AI_STATIONLIST_HPP
@@ -9,48 +10,36 @@
 #include "ai_station.hpp"
 
 /**
- * Class that creates a list of stations you own.
+ * Creates a list of stations of which you are the owner.
+ * @ingroup AIStationList
  */
 class AIStationList : public AIAbstractList {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIStationList"; }
 
 	/**
-	 * The constructor to make a list of stations.
-	 * @param type The type of station you want a list of.
+	 * @param station_type The type of station to make a list of stations for.
 	 */
-	AIStationList(AIStation::StationType type);
+	AIStationList(AIStation::StationType station_type);
 
 private:
-	/**
-	 * The name of this list, to check if a Valuator can be used on this list.
-	 */
 	const char *GetListName() const { return "AIStationList"; }
 };
 
 /**
- * Class that creates a list of stations the vehicles goes to.
+ * Creates a list of stations which the vehicle has in its orders.
+ * @ingroup AIStationList
  */
 class AIStationList_Vehicle : public AIAbstractList {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIStationList_Vehicle"; }
 
 	/**
-	 * The constructor to make a list of stations.
-	 * @param vehicle_id The vehicles to get the list of stations he goes to from.
+	 * @param vehicle_id The vehicle to get the list of stations he has in its orders from.
 	 */
 	AIStationList_Vehicle(VehicleID vehicle_id);
 
 private:
-	/**
-	 * The name of this list, to check if a Valuator can be used on this list.
-	 */
 	const char *GetListName() const { return "AIStationList"; }
 };
 
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_stationlist.hpp.sq
--- a/src/ai/api/ai_stationlist.hpp.sq	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_stationlist.hpp.sq	Tue Feb 26 18:32:35 2008 +0000
@@ -12,7 +12,7 @@
 void SQAIStationList_Register(Squirrel *engine) {
 	DefSQClass <AIStationList> SQAIStationList("AIStationList");
 	SQAIStationList.PreRegister(engine, "AIAbstractList");
-	SQAIStationList.AddConstructor<void (AIStationList::*)(AIStation::StationType type), 2>(engine, "xi");
+	SQAIStationList.AddConstructor<void (AIStationList::*)(AIStation::StationType station_type), 2>(engine, "xi");
 
 	SQAIStationList.DefSQStaticMethod(engine, &AIStationList::GetClassName, "GetClassName", 1, "x");
 
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_stationlist_valuator.cpp
--- a/src/ai/api/ai_stationlist_valuator.cpp	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_stationlist_valuator.cpp	Tue Feb 26 18:32:35 2008 +0000
@@ -4,27 +4,27 @@
 #include "ai_station.hpp"
 #include "ai_map.hpp"
 
-int32 AIStationList_vLocation::Valuate(int32 station) const
+int32 AIStationList_vLocation::Valuate(int32 station_id) const
 {
-	return AIStation::GetLocation(station);
-}
-
-int32 AIStationList_vCargoWaiting::Valuate(int32 station) const
-{
-	return AIStation::GetCargoWaiting(station, this->cargo_type);
+	return AIStation::GetLocation(station_id);
 }
 
-int32 AIStationList_vCargoRating::Valuate(int32 station) const
+int32 AIStationList_vCargoWaiting::Valuate(int32 station_id) const
 {
-	return AIStation::GetCargoRating(station, this->cargo_type);
+	return AIStation::GetCargoWaiting(station_id, this->cargo_id);
 }
 
-int32 AIStationList_vDistanceManhattanToTile::Valuate(int32 station) const
+int32 AIStationList_vCargoRating::Valuate(int32 station_id) const
 {
-	return AIMap::DistanceManhattan(this->tile, AIStation::GetLocation(station));
+	return AIStation::GetCargoRating(station_id, this->cargo_id);
 }
 
-int32 AIStationList_vDistanceSquareToTile::Valuate(int32 station) const
+int32 AIStationList_vDistanceManhattanToTile::Valuate(int32 station_id) const
 {
-	return AIMap::DistanceSquare(this->tile, AIStation::GetLocation(station));
+	return AIMap::DistanceManhattan(this->tile, AIStation::GetLocation(station_id));
 }
+
+int32 AIStationList_vDistanceSquareToTile::Valuate(int32 station_id) const
+{
+	return AIMap::DistanceSquare(this->tile, AIStation::GetLocation(station_id));
+}
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_stationlist_valuator.hpp
--- a/src/ai/api/ai_stationlist_valuator.hpp	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_stationlist_valuator.hpp	Tue Feb 26 18:32:35 2008 +0000
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file ai_stationlist_valuator.hpp all the valuators for stationlist */
+/** @file ai_stationlist_valuator.hpp all the valuators for AIStationList */
 
 #ifndef AI_STATIONLIST_VALUATOR_HPP
 #define AI_STATIONLIST_VALUATOR_HPP
@@ -9,135 +9,113 @@
 
 /**
  * Get the location for entries in an AIStationList instance.
- * @note resulting items are of the type TileIndex
- * @note the input items are of the type StationID
+ * @note Resulting items are of the type TileIndex.
+ * @note Can only operate on an AIStationList instance.
+ * @ingroup AIStationList
  */
 class AIStationList_vLocation : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIStationList_vGetLocation"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIStationList"; }
-
-	int32 Valuate(int32 station) const;
+	int32 Valuate(int32 station_id) const;
 };
 
 /**
- * Get the cargo waiting for entries in an AIStationList instance.
- * @note resulting items are of the type units
- * @note the input items are of the type StationID
+ * Get the cargo-waiting for entries in an AIStationList instance.
+ * @note Resulting items are of the type uint32 (units of cargo).
+ * @note Can only operate on an AIStationList instance.
+ * @ingroup AIStationList
  */
 class AIStationList_vCargoWaiting : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIStationList_vCargoWaiting"; }
 
 	/**
-	 * Custom constructor, we want a cargo-type as parameter.
+	 * @param cargo_id The cargo of which you want to get the amount of units waiting for.
 	 */
-	AIStationList_vCargoWaiting(CargoID cargo_type) { this->cargo_type = cargo_type; }
+	AIStationList_vCargoWaiting(CargoID cargo_id) :
+		cargo_id(cargo_id)
+	{}
 
 private:
-	CargoID cargo_type;
+	CargoID cargo_id;
 
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIStationList"; }
-
-	int32 Valuate(int32 station) const;
+	int32 Valuate(int32 station_id) const;
 };
 
 /**
  * Get the cargo rating for entries in an AIStationList instance.
- * @note resulting items are of the type percent
- * @note the input items are of the type StationID
+ * @note Resulting items are of the type int32 (percent).
+ * @note Can only operate on an AIStationList instance.
+ * @ingroup AIStationList
  */
 class AIStationList_vCargoRating : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIStationList_vCargoRating"; }
 
 	/**
-	 * Custom constructor, we want a cargo-type as parameter.
+	 * @param cargo_id The cargo of which you want to get the rating of.
 	 */
-	AIStationList_vCargoRating(CargoID cargo_type) { this->cargo_type = cargo_type; }
+	AIStationList_vCargoRating(CargoID cargo_id) :
+		cargo_id(cargo_id)
+	{}
 
 private:
-	CargoID cargo_type;
+	CargoID cargo_id;
 
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIStationList"; }
-
-	int32 Valuate(int32 station) const;
+	int32 Valuate(int32 station_id) const;
 };
 
 /**
  * Get the manhattan distance to a tile for entries in an AIStationList instance.
- * @note resulting items are of the type distance
- * @note the input items are of the type StationID
+ * @note Resulting items are of the type uint32.
+ * @note Can only operate on an AIStationList instance.
+ * @ingroup AIStationList
  */
 class AIStationList_vDistanceManhattanToTile : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIStationList_vDistanceManhattanToTile"; }
 
 	/**
-	 * Custom constructor, we want a tile as parameter.
+	 * @param tile The tile to get the distances to.
 	 */
-	AIStationList_vDistanceManhattanToTile(TileIndex tile) { this->tile = tile; }
+	AIStationList_vDistanceManhattanToTile(TileIndex tile) :
+		tile(tile)
+	{}
 
 private:
 	TileIndex tile;
 
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIStationList"; }
-
-	int32 Valuate(int32 station) const;
+	int32 Valuate(int32 station_id) const;
 };
 
 /**
  * Get the sqsuare distance to a tile for entries in an AIStationList instance.
- * @note resulting items are of the type distance
- * @note the input items are of the type StationID
+ * @note Resulting items are of the type uint32.
+ * @note Can only operate on an AIStationList instance.
+ * @ingroup AIStationList
  */
 class AIStationList_vDistanceSquareToTile : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIStationList_vDistanceSquareToTile"; }
 
 	/**
-	 * Custom constructor, we want a tile as parameter.
+	 * @param tile The tile to get the distances to.
 	 */
-	AIStationList_vDistanceSquareToTile(TileIndex tile) { this->tile = tile; }
+	AIStationList_vDistanceSquareToTile(TileIndex tile) :
+		tile(tile)
+	{}
 
 private:
 	TileIndex tile;
 
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIStationList"; }
-
-	int32 Valuate(int32 station) const;
+	int32 Valuate(int32 station_id) const;
 };
 
 #endif /* AI_STATIONLIST_VALUATOR_HPP */
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_stationlist_valuator.hpp.sq
--- a/src/ai/api/ai_stationlist_valuator.hpp.sq	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_stationlist_valuator.hpp.sq	Tue Feb 26 18:32:35 2008 +0000
@@ -31,7 +31,7 @@
 void SQAIStationList_vCargoWaiting_Register(Squirrel *engine) {
 	DefSQClass <AIStationList_vCargoWaiting> SQAIStationList_vCargoWaiting("AIStationList_vCargoWaiting");
 	SQAIStationList_vCargoWaiting.PreRegister(engine);
-	SQAIStationList_vCargoWaiting.AddConstructor<void (AIStationList_vCargoWaiting::*)(CargoID cargo_type), 2>(engine, "xi");
+	SQAIStationList_vCargoWaiting.AddConstructor<void (AIStationList_vCargoWaiting::*)(CargoID cargo_id), 2>(engine, "xi");
 
 	SQAIStationList_vCargoWaiting.DefSQStaticMethod(engine, &AIStationList_vCargoWaiting::GetClassName, "GetClassName", 1, "x");
 
@@ -50,7 +50,7 @@
 void SQAIStationList_vCargoRating_Register(Squirrel *engine) {
 	DefSQClass <AIStationList_vCargoRating> SQAIStationList_vCargoRating("AIStationList_vCargoRating");
 	SQAIStationList_vCargoRating.PreRegister(engine);
-	SQAIStationList_vCargoRating.AddConstructor<void (AIStationList_vCargoRating::*)(CargoID cargo_type), 2>(engine, "xi");
+	SQAIStationList_vCargoRating.AddConstructor<void (AIStationList_vCargoRating::*)(CargoID cargo_id), 2>(engine, "xi");
 
 	SQAIStationList_vCargoRating.DefSQStaticMethod(engine, &AIStationList_vCargoRating::GetClassName, "GetClassName", 1, "x");
 
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_tilelist.hpp
--- a/src/ai/api/ai_tilelist.hpp	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_tilelist.hpp	Tue Feb 26 18:32:35 2008 +0000
@@ -1,6 +1,7 @@
 /* $Id$ */
 
 /** @file ai_tilelist.hpp a simple tilelist which you can manipulate */
+/** @defgroup AITileList AITileList - Valuators and lists working on/with AITileList */
 
 #ifndef AI_TILELIST_HPP
 #define AI_TILELIST_HPP
@@ -9,25 +10,22 @@
 #include "../../industry.h"
 
 /**
- * Class that creates a simple empty list of tiles which you can manipulate.
+ * Creates an empty list, in which you can add tiles.
+ * @ingroup AITileList
  */
 class AITileList : public AIAbstractList {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AITileList"; }
 
 private:
-	/**
-	 * The name of this list, to check if a Valuator can be used on this list.
-	 */
 	const char *GetListName() const { return "AITileList"; }
 
 private:
 	/**
 	 * Make sure t1.x is smaller than t2.x and t1.y is smaller than t2.y.
 	 * They are swapped to ensure they are after calling this function.
+	 * @param t1 one of the corners of the rectangle.
+	 * @param t2 the other corner of the rectangle.
 	 */
 	void FixRectangleSpan(TileIndex &t1, TileIndex &t2);
 
@@ -66,39 +64,33 @@
 };
 
 /**
- * Class that creates a list of tiles that will accept cargo for the given
- *  industry.
- * @note If a simular industry is close, it might happen that this industry
- *  receives the cargo.
+ * Creates a list of tiles that will accept cargo for the given industry.
+ * @note If a simular industry is close, it might happen that this industry receives the cargo.
+ * @ingroup AITileList
  */
 class AITileList_IndustryAccepting : public AITileList {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AITileList_IndustryAccepting"; }
 
 	/**
-	 * The constructor to make a list of tiles that will accept cargo for the
-	 *  given industry.
+	 * @param industry_id The industry to create the AITileList around.
+	 * @param radius The radius of the station you will be using.
 	 */
 	AITileList_IndustryAccepting(IndustryID industry_id, uint radius);
 };
 
 /**
- * Class that creates a list of tiles which the industry checks to see if a
- *  station is there to receive cargo produced by this industry.
+ * Creates a list of tiles which the industry checks to see if a station is
+ *  there to receive cargo produced by this industry.
+ * @ingroup AITileList
  */
 class AITileList_IndustryProducing : public AITileList {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AITileList_IndustryProducing"; }
 
 	/**
-	 * The constructor to make a list of tiles which the industry checks to see
-	 * if a station is there to receive cargo produced by this industry.
+	 * @param industry_id The industry to create the AITileList around.
+	 * @param radius The radius of the station you will be using.
 	 */
 	AITileList_IndustryProducing(IndustryID industry_id, uint radius);
 };
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_tilelist_valuator.cpp
--- a/src/ai/api/ai_tilelist_valuator.cpp	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_tilelist_valuator.cpp	Tue Feb 26 18:32:35 2008 +0000
@@ -52,12 +52,12 @@
 
 int32 AITileList_vCargoAcceptance::Valuate(int32 tile) const
 {
-	return AITile::GetCargoAcceptance(tile, this->cargo_type, this->width, this->height, this->radius);
+	return AITile::GetCargoAcceptance(tile, this->cargo_id, this->width, this->height, this->radius);
 }
 
 int32 AITileList_vCargoProduction::Valuate(int32 tile) const
 {
-	return AITile::GetCargoProduction(tile, this->cargo_type, this->width, this->height, this->radius);
+	return AITile::GetCargoProduction(tile, this->cargo_id, this->width, this->height, this->radius);
 }
 
 int32 AITileList_vDistanceManhattanToTile::Valuate(int32 tile) const
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_tilelist_valuator.hpp
--- a/src/ai/api/ai_tilelist_valuator.hpp	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_tilelist_valuator.hpp	Tue Feb 26 18:32:35 2008 +0000
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file ai_tilelist_valuator.hpp all the valuators for tilelist */
+/** @file ai_tilelist_valuator.hpp all the valuators for AITileList */
 
 #ifndef AI_TILELIST_VALUATOR_HPP
 #define AI_TILELIST_VALUATOR_HPP
@@ -9,156 +9,118 @@
 
 /**
  * Check if tiles are buildable for entries in an AITileList instance.
- * @note resulting items are of the type bool (0 = not buildable, 1 = buildable)
- * @note the input items are of the type TileIndex
+ * @note Resulting items are of the type bool (0 = not buildable, 1 = buildable).
+ * @note Can only operate on an AITileList instance.
+ * @ingroup AITileList
  */
 class AITileList_vBuildable : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AITileList_vBuildable"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AITileList"; }
-
 	int32 Valuate(int32 tile) const;
 };
 
 /**
  * Check if tiles are water-tiles for entries in an AITileList instance.
- * @note resulting items are of the type bool (0 = not water-tile, 1 = water-tile)
- * @note the input items are of the type TileIndex
+ * @note Resulting items are of the type bool (0 = not water-tile, 1 = water-tile).
+ * @note Can only operate on an AITileList instance.
+ * @ingroup AITileList
  */
 class AITileList_vWater : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AITileList_vWater"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AITileList"; }
-
 	int32 Valuate(int32 tile) const;
 };
 
 /**
  * Check if tiles are buildable in a rectangle around entries in an AITileList instance, with the entry in the list as top-left.
- * @note resulting items are of the type bool (0 = not buildable, 1 = buildable)
- * @note the input items are of the type TileIndex
+ * @note Resulting items are of the type bool (0 = not buildable, 1 = buildable).
+ * @note Can only operate on an AITileList instance.
+ * @ingroup AITileList
  */
 class AITileList_vBuildableRectangle : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AITileList_vBuildableRectangle"; }
 
 	/**
-	 * Custom constructor, we want a width and height as parameter.
+	 * @param width The width of the rectangle.
+	 * @param height The height of the rectangle.
 	 */
-	AITileList_vBuildableRectangle(uint width, uint height) { this->width = width; this->height = height; }
+	AITileList_vBuildableRectangle(uint width, uint height) :
+		width(width),
+		height(height)
+	{}
 
 private:
 	uint width, height;
 
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AITileList"; }
-
 	int32 Valuate(int32 tile) const;
 };
 
 /**
  * Check how tiles in an AITileList instance are sloped.
- * @note resulting items are of the type int32 (0 = flat, > 1 = slope)
- * @note the input items are of the type TileIndex
+ * @note Resulting items are of the type int32 (0 = flat, > 1 = slope).
+ * @note Can only operate on an AITileList instance.
+ * @ingroup AITileList
  */
 class AITileList_vSlope : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AITileList_vSlope"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AITileList"; }
-
 	int32 Valuate(int32 tile) const;
 };
 
 /**
  * Check the height of the tiles in an AITileList instance.
- * @note resulting items are of the type int32 (height, ranging from 0 to 15)
- * @note the input items are of the type TileIndex
+ * @note Resulting items are of the type int32 (height, ranging from 0 to 15).
+ * @note Can only operate on an AITileList instance.
+ * @ingroup AITileList
  */
 class AITileList_vHeight : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AITileList_vHeight"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AITileList"; }
-
 	int32 Valuate(int32 tile) const;
 };
 
 /**
  * Count for each entry in AITileList the amount of neighbours that contain road.
  *   This is a value between 0 and 4, as it only check horizontal and vertical.
- * @note resulting items are of the type int32 (the amount of neighbour road tiles, value between 0 and 4)
- * @note the input items are of the type TileIndex
+ * @note Resulting items are of the type int32 (the amount of neighbour road tiles, value between 0 and 4).
+ * @note Can only operate on an AITileList instance.
+ * @ingroup AITileList
  */
 class AITileList_vNeighbourRoadCount : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AITileList_vNeighbourRoad"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AITileList"; }
-
 	int32 Valuate(int32 tile) const;
 };
 
 /**
  * Check if the tiles in AITileList have a piece of road on them.
- * @note resulting items are of the type bool (0 = no road, 1 = road)
- * @note the input items are of the type TileIndex
+ * @note Resulting items are of the type bool (0 = no road, 1 = road).
+ * @note Can only operate on an AITileList instance.
+ * @ingroup AITileList
  */
 class AITileList_vRoadTile : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AITileList_vRoadTile"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AITileList"; }
-
 	int32 Valuate(int32 tile) const;
 };
 
@@ -167,31 +129,33 @@
  * If this value is >= 8, it means it will accept this cargo. For passengers
  *  and mail it is also a good indicator how much cargo would be brought to
  *  the station.
- * @post values < 8 means this tile does not accept this cargo.
- * @note resulting items are of the type int32 (indicating acceptance)
- * @note the input items are of the type TileIndex
+ * @post Values < 8 means this tile does not accept this cargo.
+ * @note Resulting items are of the type int32 (indicating acceptance).
+ * @note Can only operate on an AITileList instance.
+ * @ingroup AITileList
  */
 class AITileList_vCargoAcceptance : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AITileList_vCargoAcceptance"; }
 
 	/**
-	 * Custom constructor, we want a cargo-type as parameter.
+	 * @param cargo_id The cargo to check the acceptance for.
+	 * @param width The width of your station.
+	 * @param height The height of your station.
+	 * @param radius The radius of your station-type.
 	 */
-	AITileList_vCargoAcceptance(CargoID cargo_type, uint width, uint height, uint radius) { this->cargo_type = cargo_type; this->width = width; this->height = height; this->radius = radius; }
+	AITileList_vCargoAcceptance(CargoID cargo_id, uint width, uint height, uint radius) :
+		cargo_id(cargo_id),
+		width(width),
+		height(height),
+		radius(radius)
+	{}
 
 private:
-	CargoID cargo_type;
+	CargoID cargo_id;
 	uint width, height, radius;
 
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AITileList"; }
-
 	int32 Valuate(int32 tile) const;
 };
 
@@ -199,87 +163,81 @@
  * Get the amount of tiles producing cargo for all tiles in AITileList.
  *  This counts the tiles that produce this cargo. It doesn't give any
  *  indication about the amount it will be producing.
- * @note town(houses) are not included in the value.
- * @note resulting items are of the type int32 (indicating tiles of production).
- * @note the input items are of the type TileIndex.
+ * @note Town(houses) are not included in the value.
+ * @note Resulting items are of the type int32 (indicating tiles of production).
+ * @note Can only operate on an AITileList instance.
+ * @ingroup AITileList
  */
 class AITileList_vCargoProduction : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AITileList_vCargoProduction"; }
 
 	/**
-	 * Custom constructor, we want a cargo-type as parameter.
+	 * @param cargo_id The cargo to check the production for.
+	 * @param width The width of your station.
+	 * @param height The height of your station.
+	 * @param radius The radius of your station-type.
 	 */
-	AITileList_vCargoProduction(CargoID cargo_type, uint width, uint height, uint radius) { this->cargo_type = cargo_type; this->width = width; this->height = height; this->radius = radius; }
+	AITileList_vCargoProduction(CargoID cargo_id, uint width, uint height, uint radius) :
+		cargo_id(cargo_id),
+		width(width),
+		height(height),
+		radius(radius)
+	{}
 
 private:
-	CargoID cargo_type;
+	CargoID cargo_id;
 	uint width, height, radius;
 
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AITileList"; }
-
 	int32 Valuate(int32 tile) const;
 };
 
 /**
  * Get the manhattan distance to a tile for entries in an AITileList instance.
- * @note resulting items are of the type distance
- * @note the input items are of the type TileIndex
+ * @note Resulting items are of the type uint32.
+ * @note Can only operate on an AITileList instance.
+ * @ingroup AITileList
  */
 class AITileList_vDistanceManhattanToTile : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AITileList_vDistanceManhattanToTile"; }
 
 	/**
-	 * Custom constructor, we want a tile as parameter.
+	 * @param tile The tile to get the distance to.
 	 */
-	AITileList_vDistanceManhattanToTile(TileIndex tile) { this->tile = tile; }
+	AITileList_vDistanceManhattanToTile(TileIndex tile) :
+		tile(tile)
+	{}
 
 private:
 	TileIndex tile;
 
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AITileList"; }
-
 	int32 Valuate(int32 station) const;
 };
 
 /**
  * Get the sqsuare distance to a tile for entries in an AITileList instance.
- * @note resulting items are of the type distance
- * @note the input items are of the type TileIndex
+ * @note Resulting items are of the type uint32.
+ * @note Can only operate on an AITileList instance.
+ * @ingroup AITileList
  */
 class AITileList_vDistanceSquareToTile : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AITileList_vDistanceSquareToTile"; }
 
 	/**
-	 * Custom constructor, we want a tile as parameter.
+	 * @param tile The tile to get the distance to.
 	 */
-	AITileList_vDistanceSquareToTile(TileIndex tile) { this->tile = tile; }
+	AITileList_vDistanceSquareToTile(TileIndex tile) :
+		tile(tile)
+	{}
 
 private:
 	TileIndex tile;
 
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AITileList"; }
-
 	int32 Valuate(int32 station) const;
 };
 
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_tilelist_valuator.hpp.sq
--- a/src/ai/api/ai_tilelist_valuator.hpp.sq	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_tilelist_valuator.hpp.sq	Tue Feb 26 18:32:35 2008 +0000
@@ -145,7 +145,7 @@
 void SQAITileList_vCargoAcceptance_Register(Squirrel *engine) {
 	DefSQClass <AITileList_vCargoAcceptance> SQAITileList_vCargoAcceptance("AITileList_vCargoAcceptance");
 	SQAITileList_vCargoAcceptance.PreRegister(engine);
-	SQAITileList_vCargoAcceptance.AddConstructor<void (AITileList_vCargoAcceptance::*)(CargoID cargo_type, uint width, uint height, uint radius), 5>(engine, "xiiii");
+	SQAITileList_vCargoAcceptance.AddConstructor<void (AITileList_vCargoAcceptance::*)(CargoID cargo_id, uint width, uint height, uint radius), 5>(engine, "xiiii");
 
 	SQAITileList_vCargoAcceptance.DefSQStaticMethod(engine, &AITileList_vCargoAcceptance::GetClassName, "GetClassName", 1, "x");
 
@@ -164,7 +164,7 @@
 void SQAITileList_vCargoProduction_Register(Squirrel *engine) {
 	DefSQClass <AITileList_vCargoProduction> SQAITileList_vCargoProduction("AITileList_vCargoProduction");
 	SQAITileList_vCargoProduction.PreRegister(engine);
-	SQAITileList_vCargoProduction.AddConstructor<void (AITileList_vCargoProduction::*)(CargoID cargo_type, uint width, uint height, uint radius), 5>(engine, "xiiii");
+	SQAITileList_vCargoProduction.AddConstructor<void (AITileList_vCargoProduction::*)(CargoID cargo_id, uint width, uint height, uint radius), 5>(engine, "xiiii");
 
 	SQAITileList_vCargoProduction.DefSQStaticMethod(engine, &AITileList_vCargoProduction::GetClassName, "GetClassName", 1, "x");
 
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_townlist.hpp
--- a/src/ai/api/ai_townlist.hpp	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_townlist.hpp	Tue Feb 26 18:32:35 2008 +0000
@@ -1,6 +1,7 @@
 /* $Id$ */
 
 /** @file ai_townlist.hpp list all the towns */
+/** @defgroup AITownList AITownList - Valuators and lists working on/with AITownList */
 
 #ifndef AI_TOWNLIST_HPP
 #define AI_TOWNLIST_HPP
@@ -8,24 +9,15 @@
 #include "ai_abstractlist.hpp"
 
 /**
- * Class that creates a list of current towns.
+ * Creates a list of towns that are currently on the map.
+ * @ingroup AITownList
  */
 class AITownList : public AIAbstractList {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AITownList"; }
-
-	/**
-	 * The constructor to make a list of towns.
-	 */
 	AITownList();
 
 private:
-	/**
-	 * The name of this list, to check if a Valuator can be used on this list.
-	 */
 	const char *GetListName() const { return "AITownList"; }
 };
 
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_townlist_valuator.cpp
--- a/src/ai/api/ai_townlist_valuator.cpp	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_townlist_valuator.cpp	Tue Feb 26 18:32:35 2008 +0000
@@ -3,11 +3,6 @@
 #include "ai_map.hpp"
 #include "ai_base.hpp"
 
-int32 AITownList_vRandomize::Valuate(int32 town) const
-{
-	return AIBase::Rand();
-}
-
 int32 AITownList_vPopulation::Valuate(int32 town) const
 {
 	return AITown::GetPopulation(town);
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_townlist_valuator.hpp
--- a/src/ai/api/ai_townlist_valuator.hpp	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_townlist_valuator.hpp	Tue Feb 26 18:32:35 2008 +0000
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file ai_townlist_valuator.hpp all the valuators for townlist */
+/** @file ai_townlist_valuator.hpp all the valuators for AITownList */
 
 #ifndef AI_TOWNLIST_VALUATOR_HPP
 #define AI_TOWNLIST_VALUATOR_HPP
@@ -8,90 +8,57 @@
 #include "ai_abstractlist.hpp"
 
 /**
- * Give a random value for the entries in an AITownList instance.
- * @note resulting items are of the type int32
- * @note the input items are of the type TownID
- */
-class AITownList_vRandomize : public AIAbstractList::Valuator {
-public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
-	static const char *GetClassName() { return "AITownList_vRandomize"; }
-
-private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
-	const char *GetListName() const { return "AITownList"; }
-
-	int32 Valuate(int32 town) const;
-};
-
-/**
  * Get the population for entries in an AITownList instance.
- * @note resulting items are of the type int32
- * @note the input items are of the type TownID
+ * @note Resulting items are of the type int32.
+ * @note Can only operate on an AITownList instance.
+ * @ingroup AITownList
  */
 class AITownList_vPopulation : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AITownList_vGetPopulation"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AITownList"; }
-
 	int32 Valuate(int32 town) const;
 };
 
 /**
  * Get the location for entries in an AITownList instance.
- * @note resulting items are of the type TileIndex
- * @note the input items are of the type TownID
+ * @note Resulting items are of the type TileIndex.
+ * @note Can only operate on an AITownList instance.
+ * @ingroup AITownList
  */
 class AITownList_vLocation : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AITownList_vGetLocation"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AITownList"; }
-
 	int32 Valuate(int32 town) const;
 };
 
 /**
  * Get the manhattan distance to a tile for entries in an AITownList instance.
- * @note resulting items are of the type distance
- * @note the input items are of the type TownID
+ * @note Resulting items are of the type uint32.
+ * @note Can only operate on an AITownList instance.
+ * @ingroup AITownList
  */
 class AITownList_vDistanceManhattanToTile : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AITownList_vDistanceManhattanToTile"; }
 
 	/**
 	 * Custom constructor, we want a tile as parameter.
 	 */
-	AITownList_vDistanceManhattanToTile(TileIndex tile) { this->tile = tile; }
+	AITownList_vDistanceManhattanToTile(TileIndex tile) :
+		tile(tile)
+	{}
 
 private:
 	TileIndex tile;
 
 	/**
-	 * The name of this list, to check if we can be used with a List.
+	 * @param tile The tile to get the distance to.
 	 */
 	const char *GetListName() const { return "AITownList"; }
 
@@ -100,29 +67,25 @@
 
 /**
  * Get the sqsuare distance to a tile for entries in an AITownList instance.
- * @note resulting items are of the type distance
- * @note the input items are of the type TownID
+ * @note Resulting items are of the type uint32.
+ * @note Can only operate on an AITownList instance.
+ * @ingroup AITownList
  */
 class AITownList_vDistanceSquareToTile : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AITownList_vDistanceSquareToTile"; }
 
 	/**
-	 * Custom constructor, we want a tile as parameter.
+	 * @param tile The tile to get the distance to.
 	 */
-	AITownList_vDistanceSquareToTile(TileIndex tile) { this->tile = tile; }
+	AITownList_vDistanceSquareToTile(TileIndex tile) :
+		tile(tile)
+	{}
 
 private:
 	TileIndex tile;
 
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AITownList"; }
-
 	int32 Valuate(int32 station) const;
 };
 
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_townlist_valuator.hpp.sq
--- a/src/ai/api/ai_townlist_valuator.hpp.sq	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_townlist_valuator.hpp.sq	Tue Feb 26 18:32:35 2008 +0000
@@ -1,25 +1,6 @@
 #include "ai_townlist_valuator.hpp"
 
 namespace SQConvert {
-	/* Allow AITownList_vRandomize to be used as Squirrel parameter */
-	template <> AITownList_vRandomize *GetParam(ForceType<AITownList_vRandomize *>, HSQUIRRELVM vm, int index) { SQUserPointer instance; sq_getinstanceup(vm, index, &instance, 0); return  (AITownList_vRandomize *)instance; }
-	template <> AITownList_vRandomize &GetParam(ForceType<AITownList_vRandomize &>, HSQUIRRELVM vm, int index) { SQUserPointer instance; sq_getinstanceup(vm, index, &instance, 0); return *(AITownList_vRandomize *)instance; }
-	template <> const AITownList_vRandomize *GetParam(ForceType<const AITownList_vRandomize *>, HSQUIRRELVM vm, int index) { SQUserPointer instance; sq_getinstanceup(vm, index, &instance, 0); return  (AITownList_vRandomize *)instance; }
-	template <> const AITownList_vRandomize &GetParam(ForceType<const AITownList_vRandomize &>, HSQUIRRELVM vm, int index) { SQUserPointer instance; sq_getinstanceup(vm, index, &instance, 0); return *(AITownList_vRandomize *)instance; }
-	template <> int Return<AITownList_vRandomize *>(HSQUIRRELVM vm, AITownList_vRandomize *res) { if (res == NULL) { sq_pushnull(vm); return 1; } res->AddRef(); Squirrel::CreateClassInstanceVM(vm, "AITownList_vRandomize", res, NULL, DefSQDestructorCallback<AITownList_vRandomize>); return 1; }
-}; // namespace SQConvert
-
-void SQAITownList_vRandomize_Register(Squirrel *engine) {
-	DefSQClass <AITownList_vRandomize> SQAITownList_vRandomize("AITownList_vRandomize");
-	SQAITownList_vRandomize.PreRegister(engine);
-	SQAITownList_vRandomize.AddConstructor<void (AITownList_vRandomize::*)(), 1>(engine, "x");
-
-	SQAITownList_vRandomize.DefSQStaticMethod(engine, &AITownList_vRandomize::GetClassName, "GetClassName", 1, "x");
-
-	SQAITownList_vRandomize.PostRegister(engine);
-}
-
-namespace SQConvert {
 	/* Allow AITownList_vPopulation to be used as Squirrel parameter */
 	template <> AITownList_vPopulation *GetParam(ForceType<AITownList_vPopulation *>, HSQUIRRELVM vm, int index) { SQUserPointer instance; sq_getinstanceup(vm, index, &instance, 0); return  (AITownList_vPopulation *)instance; }
 	template <> AITownList_vPopulation &GetParam(ForceType<AITownList_vPopulation &>, HSQUIRRELVM vm, int index) { SQUserPointer instance; sq_getinstanceup(vm, index, &instance, 0); return *(AITownList_vPopulation *)instance; }
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_vehiclelist.hpp
--- a/src/ai/api/ai_vehiclelist.hpp	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_vehiclelist.hpp	Tue Feb 26 18:32:35 2008 +0000
@@ -1,6 +1,7 @@
 /* $Id$ */
 
 /** @file ai_vehiclelist.hpp list all the vehicles (you own) */
+/** @defgroup AIVehicleList AIVehicleList - Valuators and lists working on/with AIVehicleList */
 
 #ifndef AI_VEHICLELIST_HPP
 #define AI_VEHICLELIST_HPP
@@ -8,47 +9,32 @@
 #include "ai_abstractlist.hpp"
 
 /**
- * Class that creates a list of vehicles you own.
+ * Creates a list of vehicles of which you are the owner.
+ * @ingroup AIVehicleList
  */
 class AIVehicleList : public AIAbstractList {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIVehicleList"; }
-
-	/**
-	 * The constructor to make a list of vehicles.
-	 */
 	AIVehicleList();
 
 private:
-	/**
-	 * The name of this list, to check if a Valuator can be used on this list.
-	 */
 	const char *GetListName() const { return "AIVehicleList"; }
 };
 
 /**
- * Class that creates a list of vehicles that go to a given station.
+ * Creates a list of vehicles that have orders to a given station.
+ * @ingroup AIVehicleList
  */
 class AIVehicleList_Station : public AIAbstractList {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIVehicleList_Station"; }
 
 	/**
-	 * The constructor to make a list of vehicles that goes to this station.
-	 * @param station_id The station to get the list of vehicles that go here from.
+	 * @param station_id The station to get the list of vehicles that have orders to him from.
 	 */
 	AIVehicleList_Station(StationID station_id);
 
 private:
-	/**
-	 * The name of this list, to check if a Valuator can be used on this list.
-	 */
 	const char *GetListName() const { return "AIVehicleList"; }
 };
 
diff -r 053e53a1650e -r 38560cd27070 src/ai/api/ai_vehiclelist_valuator.hpp
--- a/src/ai/api/ai_vehiclelist_valuator.hpp	Tue Feb 26 16:03:39 2008 +0000
+++ b/src/ai/api/ai_vehiclelist_valuator.hpp	Tue Feb 26 18:32:35 2008 +0000
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file ai_vehiclelist_valuator.hpp all the valuators for vehiclelist */
+/** @file ai_vehiclelist_valuator.hpp all the valuators for AIVehicleList */
 
 #ifndef AI_VEHICLELIST_VALUATOR_HPP
 #define AI_VEHICLELIST_VALUATOR_HPP
@@ -9,190 +9,136 @@
 
 /**
  * Get the location for entries in an AIVehicleList instance.
- * @note resulting items are of the type TileIndex
- * @note the input items are of the type VehicleID
+ * @note Resulting items are of the type TileIndex.
+ * @note Can only operate on an AIVehicleList instance.
+ * @ingroup AIVehicleList
  */
 class AIVehicleList_vLocation : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIVehicleList_vGetLocation"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIVehicleList"; }
-
 	int32 Valuate(int32 vehicle_id) const;
 };
 
 /**
  * Get the engine-type for entries in an AIVehicleList instance.
- * @note resulting items are of the type EngineID
- * @note the input items are of the type VehicleID
+ * @note Resulting items are of the type EngineID.
+ * @note Can only operate on an AIVehicleList instance.
+ * @ingroup AIVehicleList
  */
 class AIVehicleList_vEngineType : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIVehicleList_vEngineType"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIVehicleList"; }
-
 	int32 Valuate(int32 vehicle_id) const;
 };
 
 /**
  * Get the unit number for entries in an AIVehicleList instance.
- * @note resulting items are of the type int32
- * @note the input items are of the type VehicleID
+ * @note Resulting items are of the type int32.
+ * @note Can only operate on an AIVehicleList instance.
+ * @ingroup AIVehicleList
  */
 class AIVehicleList_vUnitNumber : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIVehicleList_vUnitNumber"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIVehicleList"; }
-
 	int32 Valuate(int32 vehicle_id) const;
 };
 
 /**
  * Get the age for entries in an AIVehicleList instance.
- * @note resulting items are of the type int32 (age in days)
- * @note the input items are of the type VehicleID
+ * @note Resulting items are of the type int32 (age in days).
+ * @note Can only operate on an AIVehicleList instance.
+ * @ingroup AIVehicleList
  */
 class AIVehicleList_vAge : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIVehicleList_vAge"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIVehicleList"; }
-
 	int32 Valuate(int32 vehicle_id) const;
 };
 
 /**
  * Get the max age for entries in an AIVehicleList instance.
- * @note resulting items are of the type int32 (age in days)
- * @note the input items are of the type VehicleID
+ * @note Resulting items are of the type int32 (age in days).
+ * @note Can only operate on an AIVehicleList instance.
+ * @ingroup AIVehicleList
  */
 class AIVehicleList_vMaxAge : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIVehicleList_vMaxAge"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIVehicleList"; }
-
 	int32 Valuate(int32 vehicle_id) const;
 };
 
 /**
  * Get the age left for the vehicle gets 'old' for entries in an AIVehicleList instance.
- * @note resulting items are of the type int32 (age in days)
- * @note the input items are of the type VehicleID
+ * @note Resulting items are of the type int32 (age in days).
+ * @note Can only operate on an AIVehicleList instance.
+ * @ingroup AIVehicleList
  */
 class AIVehicleList_vAgeLeft : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIVehicleList_vAgeLeft"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIVehicleList"; }
-
 	int32 Valuate(int32 vehicle_id) const;
 };
 
 /**
  * Get the profit of this year for entries in an AIVehicleList instance.
- * @note resulting items are of the type int32 (age in days)
- * @note the input items are of the type VehicleID
+ * @note Resulting items are of the type int32 (age in days).
+ * @note Can only operate on an AIVehicleList instance.
+ * @ingroup AIVehicleList
  */
 class AIVehicleList_vProfitThisYear : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIVehicleList_vProfitThisYear"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIVehicleList"; }
-
 	int32 Valuate(int32 vehicle_id) const;
 };
 
 /**
  * Get the profit of last year for entries in an AIVehicleList instance.
- * @note resulting items are of the type int32 (age in days)
- * @note the input items are of the type VehicleID
+ * @note Resulting items are of the type int32 (age in days).
+ * @note Can only operate on an AIVehicleList instance.
+ * @ingroup AIVehicleList
  */
 class AIVehicleList_vProfitLastYear : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIVehicleList_vProfitLastYear"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIVehicleList"; }
-
 	int32 Valuate(int32 vehicle_id) const;
 };
 
 /**
  * Get the ype of the vehicle for entries in an AIVehicleList instance.
- * @note resulting items are of the type AIVehicle::VehicleType
- * @note the input items are of the type VehicleID
+ * @note Resulting items are of the type AIVehicle::VehicleType.
+ * @note Can only operate on an AIVehicleList instance.
+ * @ingroup AIVehicleList
  */
 class AIVehicleList_vVehicleType : public AIAbstractList::Valuator {
 public:
-	/**
-	 * The name of the class, needed by several sub-processes.
-	 */
 	static const char *GetClassName() { return "AIVehicleList_vVehicleType"; }
 
 private:
-	/**
-	 * The name of this list, to check if we can be used with a List.
-	 */
 	const char *GetListName() const { return "AIVehicleList"; }
-
 	int32 Valuate(int32 vehicle_id) const;
 };