(svn r22396) -Document: some AI doxygen stuff

18 files changed, 199 insertions, 116 deletions

diff --git a/src/ai/ai_gui.cpp b/src/ai/ai_gui.cpp
index 1f57b8ebc..3fb36a09d 100644
--- a/src/ai/ai_gui.cpp
+++ b/src/ai/ai_gui.cpp
@@ -45,12 +45,17 @@ enum AIListWindowWidgets {
  * Window that let you choose an available AI.
  */
 struct AIListWindow : public Window {
-	const AIInfoList *ai_info_list;
-	int selected;
-	CompanyID slot;
-	int line_height; // Height of a row in the matrix widget.
-	Scrollbar *vscroll;
+	const AIInfoList *ai_info_list; ///< The list of AIs.
+	int selected;                   ///< The currently selected AI.
+	CompanyID slot;                 ///< The company we're selecting a new AI for.
+	int line_height;                ///< Height of a row in the matrix widget.
+	Scrollbar *vscroll;             ///< Cache of the vertical scrollbar.
 
+	/**
+	 * Constructor for the window.
+	 * @param desc The description of the window.
+	 * @param slot The company we're changing the AI for.
+	 */
 	AIListWindow(const WindowDesc *desc, CompanyID slot) : Window(),
 		slot(slot)
 	{
@@ -135,6 +140,9 @@ struct AIListWindow : public Window {
 		}
 	}
 
+	/**
+	 * Changes the AI of the current slot.
+	 */
 	void ChangeAI()
 	{
 		if (this->selected == -1) {
@@ -254,15 +262,20 @@ enum AISettingsWindowWidgest {
  * Window for settings the parameters of an AI.
  */
 struct AISettingsWindow : public Window {
-	CompanyID slot;
-	AIConfig *ai_config;
-	int clicked_button;
-	bool clicked_increase;
-	int timeout;
-	int clicked_row;
-	int line_height; // Height of a row in the matrix widget.
-	Scrollbar *vscroll;
+	CompanyID slot;        ///< The currently show company's setting.
+	AIConfig *ai_config;   ///< The configuration we're modifying.
+	int clicked_button;    ///< The button we clicked.
+	bool clicked_increase; ///< Whether we clicked the increase or decrease button.
+	int timeout;           ///< Timeout for unclicking the button.
+	int clicked_row;       ///< The clicked row of settings.
+	int line_height;       ///< Height of a row in the matrix widget.
+	Scrollbar *vscroll;    ///< Cache of the vertical scrollbar.
 
+	/**
+	 * Constructor for the window.
+	 * @param desc The description of the window.
+	 * @param slot The company we're changing the settings for.
+	 */
 	AISettingsWindow(const WindowDesc *desc, CompanyID slot) : Window(),
 		slot(slot),
 		clicked_button(-1),
@@ -341,6 +354,9 @@ struct AISettingsWindow : public Window {
 		}
 	}
 
+	/**
+	 * Check whether we modified the difficulty level or not.
+	 */
 	void CheckDifficultyLevel()
 	{
 		if (_game_mode == GM_MENU) {
@@ -556,7 +572,7 @@ static const WindowDesc _ai_config_desc(
 struct AIConfigWindow : public Window {
 	CompanyID selected_slot; ///< The currently selected AI slot or \c INVALID_COMPANY.
 	int line_height;         ///< Height of a single AI-name line.
-	Scrollbar *vscroll;
+	Scrollbar *vscroll;      ///< Cache of the vertical scrollbar.
 
 	AIConfigWindow() : Window()
 	{
@@ -754,22 +770,27 @@ enum AIDebugWindowWidgets {
  * Window with everything an AI prints via AILog.
  */
 struct AIDebugWindow : public QueryStringBaseWindow {
-	static const int top_offset;    ///< Offset of the text at the top of the ::AID_WIDGET_LOG_PANEL.
-	static const int bottom_offset; ///< Offset of the text at the bottom of the ::AID_WIDGET_LOG_PANEL.
+	static const int top_offset;    ///< Offset of the text at the top of the AID_WIDGET_LOG_PANEL.
+	static const int bottom_offset; ///< Offset of the text at the bottom of the AID_WIDGET_LOG_PANEL.
 
-	static const unsigned int MAX_BREAK_STR_STRING_LENGTH = 256;
+	static const unsigned int MAX_BREAK_STR_STRING_LENGTH = 256; ///< Maximum length of the break string.
 
 	static CompanyID ai_debug_company;                     ///< The AI that is (was last) being debugged.
-	int redraw_timer;
-	int last_vscroll_pos;
-	bool autoscroll;
-	bool show_break_box;
+	int redraw_timer;                                      ///< Timer for redrawing the window, otherwise it'll happen every tick.
+	int last_vscroll_pos;                                  ///< Last position of the scrolling.
+	bool autoscroll;                                       ///< Whether automatically scrolling should be enabled or not.
+	bool show_break_box;                                   ///< Whether the break/debug box is visible.
 	static bool break_check_enabled;                       ///< Stop an AI when it prints a matching string
 	static char break_string[MAX_BREAK_STR_STRING_LENGTH]; ///< The string to match to the AI output
 	static bool case_sensitive_break_check;                ///< Is the matching done case-sensitive
 	int highlight_row;                                     ///< The output row that matches the given string, or -1
-	Scrollbar *vscroll;
+	Scrollbar *vscroll;                                    ///< Cache of the vertical scrollbar.
 
+	/**
+	 * Constructor for the window.
+	 * @param desc The description of the window.
+	 * @param number The window number (actually unused).
+	 */
 	AIDebugWindow(const WindowDesc *desc, WindowNumber number) : QueryStringBaseWindow(MAX_BREAK_STR_STRING_LENGTH)
 	{
 		this->CreateNestedTree(desc);
@@ -969,6 +990,10 @@ struct AIDebugWindow : public QueryStringBaseWindow {
 		}
 	}
 
+	/**
+	 * Change all settings to select another AI.
+	 * @param show_ai The new AI to show.
+	 */
 	void ChangeToAI(CompanyID show_ai)
 	{
 		this->RaiseWidget(ai_debug_company + AID_WIDGET_COMPANY_BUTTON_START);
diff --git a/src/ai/ai_info.hpp b/src/ai/ai_info.hpp
index ace456a79..936237418 100644
--- a/src/ai/ai_info.hpp
+++ b/src/ai/ai_info.hpp
@@ -63,6 +63,10 @@ protected:
 /** All static information from an AI like name, version, etc. */
 class AIInfo : public AIFileInfo {
 public:
+	/**
+	 * Get the class name, so the script code can create the right code.
+	 * @return The class name.
+	 */
 	static const char *GetClassName() { return "AIInfo"; }
 
 	AIInfo();
diff --git a/src/ai/ai_instance.hpp b/src/ai/ai_instance.hpp
index 9a427c8c6..718531feb 100644
--- a/src/ai/ai_instance.hpp
+++ b/src/ai/ai_instance.hpp
@@ -24,6 +24,11 @@ typedef void (AISuspendCallbackProc)(class AIInstance *instance);
  */
 class AI_VMSuspend {
 public:
+	/**
+	 * Create the suspend exception.
+	 * @param time The amount of ticks to suspend.
+	 * @param callback The callback to call when the AI may resume again.
+	 */
 	AI_VMSuspend(int time, AISuspendCallbackProc *callback) :
 		time(time),
 		callback(callback)
@@ -51,20 +56,33 @@ private:
  */
 class AI_FatalError {
 public:
+	/**
+	 * Creates a "fatal error" exception.
+	 * @param msg The message describing the cause of the fatal error.
+	 */
 	AI_FatalError(const char *msg) :
 		msg(msg)
 	{}
 
+	/**
+	 * The error message associated with the fatal error.
+	 * @return The error message.
+	 */
 	const char *GetErrorMessage() { return msg; }
 
 private:
-	const char *msg;
+	const char *msg; ///< The error message.
 };
 
 /** Runtime information about an AI like a pointer to the squirrel vm and the current state. */
 class AIInstance {
 public:
 	friend class AIObject;
+
+	/**
+	 * Create a new AI.
+	 * @param info The AI to create the instance of.
+	 */
 	AIInstance(class AIInfo *info);
 	~AIInstance();
 
diff --git a/src/ai/ai_scanner.hpp b/src/ai/ai_scanner.hpp
index fee16d608..f3d0776c6 100644
--- a/src/ai/ai_scanner.hpp
+++ b/src/ai/ai_scanner.hpp
@@ -38,6 +38,10 @@ public:
 	 */
 	void RegisterAI(class AIInfo *info);
 
+	/**
+	 * Register the dummy AI.
+	 * @param info The dummy AI that.
+	 */
 	void SetDummyAI(class AIInfo *info) { this->info_dummy = info; }
 
 	/**
@@ -79,7 +83,7 @@ public:
 	bool HasAI(const struct ContentInfo *ci, bool md5sum);
 #endif
 private:
-	typedef std::map<const char *, class AILibrary *, StringCompare> AILibraryList;
+	typedef std::map<const char *, class AILibrary *, StringCompare> AILibraryList; ///< Type for the list of libraries.
 
 	/**
 	 * Scan the AI dir for scripts.
@@ -91,10 +95,10 @@ private:
 	 */
 	void Reset();
 
-	AIInfo *info_dummy;
-	AIInfoList info_list;
-	AIInfoList info_single_list;
-	AILibraryList library_list;
+	AIInfo *info_dummy;          ///< The dummy AI.
+	AIInfoList info_list;        ///< The list of all AIs.
+	AIInfoList info_single_list; ///< The list of all unique AIs, based on shortname. The best AI (highest version) is shown.
+	AILibraryList library_list;  ///< The list of libraries.
 };
 
 #endif /* AI_SCANNER_HPP */
diff --git a/src/ai/api/ai_accounting.hpp b/src/ai/api/ai_accounting.hpp
index 1d4fc9085..976513269 100644
--- a/src/ai/api/ai_accounting.hpp
+++ b/src/ai/api/ai_accounting.hpp
@@ -62,7 +62,7 @@ public:
 	void ResetCosts();
 
 private:
-	Money last_costs;
+	Money last_costs; ///< The last cost we did return.
 };
 
 #endif /* AI_ACCOUNTING_HPP */
diff --git a/src/ai/api/ai_bridge.cpp b/src/ai/api/ai_bridge.cpp
index a051e85a2..8550b3df5 100644
--- a/src/ai/api/ai_bridge.cpp
+++ b/src/ai/api/ai_bridge.cpp
@@ -35,6 +35,10 @@
 	return (BridgeID)::GetBridgeType(tile);
 }
 
+/**
+ * Helper function to connect a just built bridge to nearby roads.
+ * @param instance The AI we have to built the road for.
+ */
 static void _DoCommandReturnBuildBridge2(class AIInstance *instance)
 {
 	if (!AIBridge::_BuildBridgeRoad2()) {
@@ -47,6 +51,10 @@ static void _DoCommandReturnBuildBridge2(class AIInstance *instance)
 	NOT_REACHED();
 }
 
+/**
+ * Helper function to connect a just built bridge to nearby roads.
+ * @param instance The AI we have to built the road for.
+ */
 static void _DoCommandReturnBuildBridge1(class AIInstance *instance)
 {
 	if (!AIBridge::_BuildBridgeRoad1()) {
@@ -90,7 +98,7 @@ static void _DoCommandReturnBuildBridge1(class AIInstance *instance)
 
 	AIObject::SetCallbackVariable(0, start);
 	AIObject::SetCallbackVariable(1, end);
-	return AIObject::DoCommand(end, start, type | bridge_id, CMD_BUILD_BRIDGE, NULL, &_DoCommandReturnBuildBridge1);
+	return AIObject::DoCommand(end, start, type | bridge_id, CMD_BUILD_BRIDGE, NULL, &::_DoCommandReturnBuildBridge1);
 }
 
 /* static */ bool AIBridge::_BuildBridgeRoad1()
@@ -102,7 +110,7 @@ static void _DoCommandReturnBuildBridge1(class AIInstance *instance)
 	DiagDirection dir_1 = ::DiagdirBetweenTiles(end, start);
 	DiagDirection dir_2 = ::ReverseDiagDir(dir_1);
 
-	return AIObject::DoCommand(start + ::TileOffsByDiagDir(dir_1), ::DiagDirToRoadBits(dir_2) | (AIObject::GetRoadType() << 4), 0, CMD_BUILD_ROAD, NULL, &_DoCommandReturnBuildBridge2);
+	return AIObject::DoCommand(start + ::TileOffsByDiagDir(dir_1), ::DiagDirToRoadBits(dir_2) | (AIObject::GetRoadType() << 4), 0, CMD_BUILD_ROAD, NULL, &::_DoCommandReturnBuildBridge2);
 }
 
 /* static */ bool AIBridge::_BuildBridgeRoad2()
diff --git a/src/ai/api/ai_changelog.hpp b/src/ai/api/ai_changelog.hpp
index 8cebbb3e3..d9cc76e3a 100644
--- a/src/ai/api/ai_changelog.hpp
+++ b/src/ai/api/ai_changelog.hpp
@@ -141,7 +141,7 @@
  *     default for aircraft. It is not necessarily true. This means that even
  *     if the aircraft can carry mail (as secondary cargo) it does not return
  *     true if the aircraft cannot carry it as its only cargo.
- * \li Improve behaviour of (AIEngine|AIEventEnginePreview)::GetCargoType()
+ * \li Improve behaviour of AIEngine::GetCargoType(), AIEventEnginePreview::GetCargoType()
  *     and AIEngine::CanRefitCargo() for articulated vehicles. For
  *     CanRefitCargo true is returned if at least one part can be refitted.
  *     For GetCargoType the first most used cargo type is returned.
diff --git a/src/ai/api/ai_controller.hpp b/src/ai/api/ai_controller.hpp
index 03dd77ef4..2ab7c245b 100644
--- a/src/ai/api/ai_controller.hpp
+++ b/src/ai/api/ai_controller.hpp
@@ -103,11 +103,11 @@ public:
 	static void Print(bool error_msg, const char *message);
 
 private:
-	typedef std::map<const char *, const char *, StringCompare> LoadedLibraryList;
+	typedef std::map<const char *, const char *, StringCompare> LoadedLibraryList; ///< The type for loaded libraries.
 
-	uint ticks;
-	LoadedLibraryList loaded_library;
-	int loaded_library_count;
+	uint ticks;                       ///< The amount of ticks we're sleeping.
+	LoadedLibraryList loaded_library; ///< The libraries we loaded.
+	int loaded_library_count;         ///< The amount of libraries.
 
 	/**
 	 * Register all classes that are known inside the NoAI API.
diff --git a/src/ai/api/ai_error.hpp b/src/ai/api/ai_error.hpp
index c2dd8ba95..44e4573d4 100644
--- a/src/ai/api/ai_error.hpp
+++ b/src/ai/api/ai_error.hpp
@@ -172,11 +172,11 @@ public:
 #endif /* EXPORT_SKIP */
 
 private:
-	typedef std::map<StringID, AIErrorType> AIErrorMap;
-	typedef std::map<AIErrorType, const char *> AIErrorMapString;
+	typedef std::map<StringID, AIErrorType> AIErrorMap;           ///< The type for mapping between error (internal OpenTTD) StringID to the AI error type.
+	typedef std::map<AIErrorType, const char *> AIErrorMapString; ///< The type for mapping between error type and textual representation.
 
-	static AIErrorMap error_map;
-	static AIErrorMapString error_map_string;
+	static AIErrorMap error_map;              ///< The mapping between error (internal OpenTTD) StringID to the AI error type.
+	static AIErrorMapString error_map_string; ///< The mapping between error type and textual representation.
 };
 
 #endif /* AI_ERROR_HPP */
diff --git a/src/ai/api/ai_event.cpp b/src/ai/api/ai_event.cpp
index 32edd1a0e..d659aea60 100644
--- a/src/ai/api/ai_event.cpp
+++ b/src/ai/api/ai_event.cpp
@@ -14,8 +14,9 @@
 
 #include <queue>
 
+/** The queue of events for an AI. */
 struct AIEventData {
-	std::queue<AIEvent *> stack;
+	std::queue<AIEvent *> stack; ///< The actual queue.
 };
 
 /* static */ void AIEventController::CreateEventPointer()
diff --git a/src/ai/api/ai_event_types.hpp b/src/ai/api/ai_event_types.hpp
index 51bfa6cd9..41cbc1965 100644
--- a/src/ai/api/ai_event_types.hpp
+++ b/src/ai/api/ai_event_types.hpp
@@ -74,9 +74,9 @@ public:
 	CrashReason GetCrashReason() { return this->crash_reason; }
 
 private:
-	TileIndex crash_site;
-	VehicleID vehicle;
-	CrashReason crash_reason;
+	TileIndex crash_site;     ///< The location of the crash.
+	VehicleID vehicle;        ///< The crashed vehicle.
+	CrashReason crash_reason; ///< The reason for crashing.
 };
 
 /**
@@ -109,7 +109,7 @@ public:
 	SubsidyID GetSubsidyID() { return this->subsidy_id; }
 
 private:
-	SubsidyID subsidy_id;
+	SubsidyID subsidy_id; ///< The subsidy that got offered.
 };
 
 /**
@@ -142,7 +142,7 @@ public:
 	SubsidyID GetSubsidyID() { return this->subsidy_id; }
 
 private:
-	SubsidyID subsidy_id;
+	SubsidyID subsidy_id; ///< The subsidy offer that expired.
 };
 
 /**
@@ -175,7 +175,7 @@ public:
 	SubsidyID GetSubsidyID() { return this->subsidy_id; }
 
 private:
-	SubsidyID subsidy_id;
+	SubsidyID subsidy_id; ///< The subsidy that was awared.
 };
 
 /**
@@ -208,7 +208,7 @@ public:
 	 SubsidyID GetSubsidyID() { return this->subsidy_id; }
 
 private:
-	SubsidyID subsidy_id;
+	SubsidyID subsidy_id; ///< The subsidy that expired.
 };
 
 /**
@@ -278,11 +278,11 @@ public:
 	 */
 	Money GetRunningCost();
 
-#ifdef DOXYGEN_SKIP
 	/**
 	 * Get the type of the offered engine.
 	 * @return The type the engine has.
 	 */
+#ifdef DOXYGEN_SKIP
 	AIVehicle::VehicleType GetVehicleType();
 #else
 	int32 GetVehicleType();
@@ -295,7 +295,12 @@ public:
 	bool AcceptPreview();
 
 private:
-	EngineID engine;
+	EngineID engine; ///< The engine the preview is for.
+
+	/**
+	 * Check whether the engine from this preview is still valid.
+	 * @return True iff the engine is still valid.
+	 */
 	bool IsEngineValid() const;
 };
 
@@ -329,7 +334,7 @@ public:
 	AICompany::CompanyID GetCompanyID() { return this->owner; }
 
 private:
-	AICompany::CompanyID owner;
+	AICompany::CompanyID owner; ///< The new company.
 };
 
 /**
@@ -363,7 +368,7 @@ public:
 	AICompany::CompanyID GetCompanyID() { return this->owner; }
 
 private:
-	AICompany::CompanyID owner;
+	AICompany::CompanyID owner; ///< The company that is in trouble.
 };
 
 /**
@@ -411,8 +416,8 @@ public:
 	bool AcceptMerger();
 
 private:
-	AICompany::CompanyID owner;
-	int32 value;
+	AICompany::CompanyID owner; ///< The company that is in trouble.
+	int32 value;                ///< The value of the company, i.e. the amount you would pay.
 };
 
 /**
@@ -457,8 +462,8 @@ public:
 	AICompany::CompanyID GetNewCompanyID() { return this->new_owner; }
 
 private:
-	AICompany::CompanyID old_owner;
-	AICompany::CompanyID new_owner;
+	AICompany::CompanyID old_owner; ///< The company that ended to exist.
+	AICompany::CompanyID new_owner; ///< The company that's the end result of the merger.
 };
 
 /**
@@ -491,7 +496,7 @@ public:
 	AICompany::CompanyID GetCompanyID() { return this->owner; }
 
 private:
-	AICompany::CompanyID owner;
+	AICompany::CompanyID owner; ///< The company that has gone bankrupt.
 };
 
 /**
@@ -524,7 +529,7 @@ public:
 	VehicleID GetVehicleID() { return this->vehicle_id; }
 
 private:
-	VehicleID vehicle_id;
+	VehicleID vehicle_id; ///< The vehicle that is lost.
 };
 
 /**
@@ -557,7 +562,7 @@ public:
 	VehicleID GetVehicleID() { return this->vehicle_id; }
 
 private:
-	VehicleID vehicle_id;
+	VehicleID vehicle_id; ///< The vehicle that is waiting in the depot.
 };
 
 /**
@@ -590,7 +595,7 @@ public:
 	VehicleID GetVehicleID() { return this->vehicle_id; }
 
 private:
-	VehicleID vehicle_id;
+	VehicleID vehicle_id; ///< The vehicle that is unprofitable.
 };
 
 /**
@@ -623,7 +628,7 @@ public:
 	IndustryID GetIndustryID() { return this->industry_id; }
 
 private:
-	IndustryID industry_id;
+	IndustryID industry_id; ///< The industry that opened.
 };
 
 /**
@@ -656,7 +661,7 @@ public:
 	IndustryID GetIndustryID() { return this->industry_id; }
 
 private:
-	IndustryID industry_id;
+	IndustryID industry_id; ///< The industry that closed.
 };
 
 /**
@@ -689,7 +694,7 @@ public:
 	EngineID GetEngineID() { return this->engine; }
 
 private:
-	EngineID engine;
+	EngineID engine; ///< The engine that became available.
 };
 
 /**
@@ -730,8 +735,8 @@ public:
 	VehicleID GetVehicleID() { return this->vehicle; }
 
 private:
-	StationID station;
-	VehicleID vehicle;
+	StationID station; ///< The station the vehicle arived at.
+	VehicleID vehicle; ///< The vehicle that arrived at the station.
 };
 
 /**
@@ -764,7 +769,7 @@ public:
 	StationID GetStationID() { return this->station; }
 
 private:
-	StationID station;
+	StationID station; ///< The station the zeppeliner crashed.
 };
 
 /**
@@ -797,7 +802,7 @@ public:
 	StationID GetStationID() { return this->station; }
 
 private:
-	StationID station;
+	StationID station; ///< The station the zeppeliner crashed.
 };
 
 /**
@@ -830,7 +835,7 @@ public:
 	TownID GetTownID() { return this->town; }
 
 private:
-	TownID town;
+	TownID town; ///< The town that got founded.
 };
 
 #endif /* AI_EVENT_TYPES_HPP */
diff --git a/src/ai/api/ai_execmode.hpp b/src/ai/api/ai_execmode.hpp
index f5d2a5398..569cc6526 100644
--- a/src/ai/api/ai_execmode.hpp
+++ b/src/ai/api/ai_execmode.hpp
@@ -27,8 +27,8 @@ public:
 	static const char *GetClassName() { return "AIExecMode"; }
 
 private:
-	AIModeProc *last_mode;
-	AIObject *last_instance;
+	AIModeProc *last_mode;   ///< The previous mode we were in.
+	AIObject *last_instance; ///< The previous instace of the mode.
 
 protected:
 	/**
diff --git a/src/ai/api/ai_list.cpp b/src/ai/api/ai_list.cpp
index e41b7e69c..2188d6674 100644
--- a/src/ai/api/ai_list.cpp
+++ b/src/ai/api/ai_list.cpp
@@ -19,7 +19,9 @@
  */
 class AIListSorter {
 protected:
-	AIList *list;
+	AIList *list;           ///< The list that's being sorted.
+	bool has_no_more_items; ///< Whether we have more items to iterate over.
+	int32 item_next;        ///< The next item we will show.
 
 public:
 	/**
@@ -45,7 +47,10 @@ public:
 	/**
 	 * See if the sorter has reached the end.
 	 */
-	virtual bool IsEnd() = 0;
+	bool IsEnd()
+	{
+		return this->list->buckets.empty() || this->has_no_more_items;
+	}
 
 	/**
 	 * Callback from the list if an item gets removed.
@@ -58,13 +63,15 @@ public:
  */
 class AIListSorterValueAscending : public AIListSorter {
 private:
-	AIList::AIListBucket::iterator bucket_iter;
-	AIList::AIItemList *bucket_list;
-	AIList::AIItemList::iterator bucket_list_iter;
-	bool has_no_more_items;
-	int32 item_next;
+	AIList::AIListBucket::iterator bucket_iter;    ///< The iterator over the list to find the buckets.
+	AIList::AIItemList *bucket_list;               ///< The current bucket list we're iterator over.
+	AIList::AIItemList::iterator bucket_list_iter; ///< The iterator over the bucket list.
 
 public:
+	/**
+	 * Create a new sorter.
+	 * @param list The list to sort.
+	 */
 	AIListSorterValueAscending(AIList *list)
 	{
 		this->list = list;
@@ -93,6 +100,9 @@ public:
 		this->item_next = 0;
 	}
 
+	/**
+	 * Find the next item, and store that information.
+	 */
 	void FindNext()
 	{
 		if (this->bucket_list == NULL) {
@@ -132,11 +142,6 @@ public:
 			return;
 		}
 	}
-
-	bool IsEnd()
-	{
-		return this->list->buckets.empty() || this->has_no_more_items;
-	}
 };
 
 /**
@@ -144,13 +149,15 @@ public:
  */
 class AIListSorterValueDescending : public AIListSorter {
 private:
-	AIList::AIListBucket::iterator bucket_iter;
-	AIList::AIItemList *bucket_list;
-	AIList::AIItemList::iterator bucket_list_iter;
-	bool has_no_more_items;
-	int32 item_next;
+	AIList::AIListBucket::iterator bucket_iter;    ///< The iterator over the list to find the buckets.
+	AIList::AIItemList *bucket_list;               ///< The current bucket list we're iterator over.
+	AIList::AIItemList::iterator bucket_list_iter; ///< The iterator over the bucket list.
 
 public:
+	/**
+	 * Create a new sorter.
+	 * @param list The list to sort.
+	 */
 	AIListSorterValueDescending(AIList *list)
 	{
 		this->list = list;
@@ -184,6 +191,9 @@ public:
 		this->item_next = 0;
 	}
 
+	/**
+	 * Find the next item, and store that information.
+	 */
 	void FindNext()
 	{
 		if (this->bucket_list == NULL) {
@@ -226,11 +236,6 @@ public:
 			return;
 		}
 	}
-
-	bool IsEnd()
-	{
-		return this->list->buckets.empty() || this->has_no_more_items;
-	}
 };
 
 /**
@@ -238,11 +243,13 @@ public:
  */
 class AIListSorterItemAscending : public AIListSorter {
 private:
-	AIList::AIListMap::iterator item_iter;
-	bool has_no_more_items;
-	int32 item_next;
+	AIList::AIListMap::iterator item_iter; ///< The iterator over the items in the map.
 
 public:
+	/**
+	 * Create a new sorter.
+	 * @param list The list to sort.
+	 */
 	AIListSorterItemAscending(AIList *list)
 	{
 		this->list = list;
@@ -267,6 +274,9 @@ public:
 		this->has_no_more_items = true;
 	}
 
+	/**
+	 * Find the next item, and store that information.
+	 */
 	void FindNext()
 	{
 		if (this->item_iter == this->list->items.end()) {
@@ -296,11 +306,6 @@ public:
 			return;
 		}
 	}
-
-	bool IsEnd()
-	{
-		return this->list->items.empty() || this->has_no_more_items;
-	}
 };
 
 /**
@@ -308,11 +313,13 @@ public:
  */
 class AIListSorterItemDescending : public AIListSorter {
 private:
-	AIList::AIListMap::iterator item_iter;
-	bool has_no_more_items;
-	int32 item_next;
+	AIList::AIListMap::iterator item_iter; ///< The iterator over the items in the map.
 
 public:
+	/**
+	 * Create a new sorter.
+	 * @param list The list to sort.
+	 */
 	AIListSorterItemDescending(AIList *list)
 	{
 		this->list = list;
@@ -338,6 +345,9 @@ public:
 		this->has_no_more_items = true;
 	}
 
+	/**
+	 * Find the next item, and store that information.
+	 */
 	void FindNext()
 	{
 		if (this->item_iter == this->list->items.end()) {
@@ -367,11 +377,6 @@ public:
 			return;
 		}
 	}
-
-	bool IsEnd()
-	{
-		return this->list->items.empty() || this->has_no_more_items;
-	}
 };
 
 
diff --git a/src/ai/api/ai_object.cpp b/src/ai/api/ai_object.cpp
index f2ddbebae..53f09d11a 100644
--- a/src/ai/api/ai_object.cpp
+++ b/src/ai/api/ai_object.cpp
@@ -21,6 +21,10 @@
 #include "../ai_instance.hpp"
 #include "ai_error.hpp"
 
+/**
+ * Get the storage associated with the current AIInstance.
+ * @return The storage.
+ */
 static AIStorage *GetStorage()
 {
 	return AIInstance::GetStorage();
diff --git a/src/ai/api/ai_object.hpp b/src/ai/api/ai_object.hpp
index 06d0f9edb..e928bef23 100644
--- a/src/ai/api/ai_object.hpp
+++ b/src/ai/api/ai_object.hpp
@@ -148,6 +148,7 @@ protected:
 	 * from CanSuspend() if the reason we are not allowed
 	 * to execute a DoCommand is in squirrel and not the API.
 	 * In that case use this function to restore the previous value.
+	 * @return True iff DoCommands are allowed in the current scope.
 	 */
 	static bool GetAllowDoCommand();
 
diff --git a/src/ai/api/ai_order.cpp b/src/ai/api/ai_order.cpp
index 752291751..0c646f052 100644
--- a/src/ai/api/ai_order.cpp
+++ b/src/ai/api/ai_order.cpp
@@ -512,7 +512,7 @@ static void _DoCommandReturnSetOrderFlags(class AIInstance *instance)
 	EnforcePrecondition(false, (order_flags & AIOF_GOTO_NEAREST_DEPOT) == (current & AIOF_GOTO_NEAREST_DEPOT));
 
 	if ((current & AIOF_NON_STOP_FLAGS) != (order_flags & AIOF_NON_STOP_FLAGS)) {
-		return AIObject::DoCommand(0, vehicle_id | (order_position << 20), (order_flags & AIOF_NON_STOP_FLAGS) << 4 | MOF_NON_STOP, CMD_MODIFY_ORDER, NULL, &_DoCommandReturnSetOrderFlags);
+		return AIObject::DoCommand(0, vehicle_id | (order_position << 20), (order_flags & AIOF_NON_STOP_FLAGS) << 4 | MOF_NON_STOP, CMD_MODIFY_ORDER, NULL, &::_DoCommandReturnSetOrderFlags);
 	}
 
 	switch (order->GetType()) {
@@ -521,16 +521,16 @@ static void _DoCommandReturnSetOrderFlags(class AIInstance *instance)
 				uint data = DA_ALWAYS_GO;
 				if (order_flags & AIOF_SERVICE_IF_NEEDED) data = DA_SERVICE;
 				if (order_flags & AIOF_STOP_IN_DEPOT) data = DA_STOP;
-				return AIObject::DoCommand(0, vehicle_id | (order_position << 20), (data << 4) | MOF_DEPOT_ACTION, CMD_MODIFY_ORDER, NULL, &_DoCommandReturnSetOrderFlags);
+				return AIObject::DoCommand(0, vehicle_id | (order_position << 20), (data << 4) | MOF_DEPOT_ACTION, CMD_MODIFY_ORDER, NULL, &::_DoCommandReturnSetOrderFlags);
 			}
 			break;
 
 		case OT_GOTO_STATION:
 			if ((current & AIOF_UNLOAD_FLAGS) != (order_flags & AIOF_UNLOAD_FLAGS)) {
-				return AIObject::DoCommand(0, vehicle_id | (order_position << 20), (order_flags & AIOF_UNLOAD_FLAGS) << 2 | MOF_UNLOAD, CMD_MODIFY_ORDER, NULL, &_DoCommandReturnSetOrderFlags);
+				return AIObject::DoCommand(0, vehicle_id | (order_position << 20), (order_flags & AIOF_UNLOAD_FLAGS) << 2 | MOF_UNLOAD, CMD_MODIFY_ORDER, NULL, &::_DoCommandReturnSetOrderFlags);
 			}
 			if ((current & AIOF_LOAD_FLAGS) != (order_flags & AIOF_LOAD_FLAGS)) {
-				return AIObject::DoCommand(0, vehicle_id | (order_position << 20), (order_flags & AIOF_LOAD_FLAGS) >> 1 | MOF_LOAD, CMD_MODIFY_ORDER, NULL, &_DoCommandReturnSetOrderFlags);
+				return AIObject::DoCommand(0, vehicle_id | (order_position << 20), (order_flags & AIOF_LOAD_FLAGS) >> 1 | MOF_LOAD, CMD_MODIFY_ORDER, NULL, &::_DoCommandReturnSetOrderFlags);
 			}
 			break;
 
diff --git a/src/ai/api/ai_testmode.hpp b/src/ai/api/ai_testmode.hpp
index a5596727e..c82ce7891 100644
--- a/src/ai/api/ai_testmode.hpp
+++ b/src/ai/api/ai_testmode.hpp
@@ -29,8 +29,8 @@ public:
 	static const char *GetClassName() { return "AITestMode"; }
 
 private:
-	AIModeProc *last_mode;
-	AIObject *last_instance;
+	AIModeProc *last_mode;   ///< The previous mode we were in.
+	AIObject *last_instance; ///< The previous instace of the mode.
 
 protected:
 	/**
diff --git a/src/ai/api/ai_tunnel.cpp b/src/ai/api/ai_tunnel.cpp
index 59055af2f..99aec30c4 100644
--- a/src/ai/api/ai_tunnel.cpp
+++ b/src/ai/api/ai_tunnel.cpp
@@ -46,6 +46,10 @@
 	return tile;
 }
 
+/**
+ * Helper function to connect a just built tunnel to nearby roads.
+ * @param instance The AI we have to built the road for.
+ */
 static void _DoCommandReturnBuildTunnel2(class AIInstance *instance)
 {
 	if (!AITunnel::_BuildTunnelRoad2()) {
@@ -58,6 +62,10 @@ static void _DoCommandReturnBuildTunnel2(class AIInstance *instance)
 	NOT_REACHED();
 }
 
+/**
+ * Helper function to connect a just built tunnel to nearby roads.
+ * @param instance The AI we have to built the road for.
+ */
 static void _DoCommandReturnBuildTunnel1(class AIInstance *instance)
 {
 	if (!AITunnel::_BuildTunnelRoad1()) {
@@ -91,7 +99,7 @@ static void _DoCommandReturnBuildTunnel1(class AIInstance *instance)
 	}
 
 	AIObject::SetCallbackVariable(0, start);
-	return AIObject::DoCommand(start, type, 0, CMD_BUILD_TUNNEL, NULL, &_DoCommandReturnBuildTunnel1);
+	return AIObject::DoCommand(start, type, 0, CMD_BUILD_TUNNEL, NULL, &::_DoCommandReturnBuildTunnel1);
 }
 
 /* static */ bool AITunnel::_BuildTunnelRoad1()
@@ -103,7 +111,7 @@ static void _DoCommandReturnBuildTunnel1(class AIInstance *instance)
 	DiagDirection dir_1 = ::DiagdirBetweenTiles(end, start);
 	DiagDirection dir_2 = ::ReverseDiagDir(dir_1);
 
-	return AIObject::DoCommand(start + ::TileOffsByDiagDir(dir_1), ::DiagDirToRoadBits(dir_2) | (AIObject::GetRoadType() << 4), 0, CMD_BUILD_ROAD, NULL, &_DoCommandReturnBuildTunnel2);
+	return AIObject::DoCommand(start + ::TileOffsByDiagDir(dir_1), ::DiagDirToRoadBits(dir_2) | (AIObject::GetRoadType() << 4), 0, CMD_BUILD_ROAD, NULL, &::_DoCommandReturnBuildTunnel2);
 }
 
 /* static */ bool AITunnel::_BuildTunnelRoad2()