(svn r20271) -Doc: add doxygen comments to several items under src/ai/

11 files changed, 110 insertions, 36 deletions

diff --git a/src/ai/ai.hpp b/src/ai/ai.hpp
index ef0f6fc18..387812993 100644
--- a/src/ai/ai.hpp
+++ b/src/ai/ai.hpp
@@ -18,9 +18,12 @@
 #include "../core/string_compare_type.hpp"
 #include <map>
 
+/** A list that maps AI names to their AIInfo object. */
 typedef std::map<const char *, class AIInfo *, StringCompare> AIInfoList;
 
-
+/**
+ * Main AI class. Contains all functions needed to start, stop, save and load AIs.
+ */
 class AI {
 public:
 	/**
@@ -121,18 +124,29 @@ public:
 	 */
 	static int GetStartNextTime();
 
+	/** Wrapper function for AIScanner::GetAIConsoleList */
 	static char *GetConsoleList(char *p, const char *last);
+	/** Wrapper function for AIScanner::GetAIInfoList */
 	static const AIInfoList *GetInfoList();
+	/** Wrapper function for AIScanner::GetUniqueAIInfoList */
 	static const AIInfoList *GetUniqueInfoList();
+	/** Wrapper function for AIScanner::FindInfo */
 	static AIInfo *FindInfo(const char *name, int version, bool force_exact_match);
+	/** Wrapper function for AIScanner::ImportLibrary */
 	static bool ImportLibrary(const char *library, const char *class_name, int version, HSQUIRRELVM vm);
+
+	/**
+	 * Rescans all searchpaths for available AIs. If a used AI is no longer
+	 * found it is removed from the config.
+	 */
 	static void Rescan();
 #if defined(ENABLE_NETWORK)
+	/** Wrapper function for AIScanner::HasAI */
 	static bool HasAI(const struct ContentInfo *ci, bool md5sum);
 #endif
 private:
-	static uint frame_counter;
-	static class AIScanner *ai_scanner;
+	static uint frame_counter;          //!< Tick counter for the AI code
+	static class AIScanner *ai_scanner; //!< AIScanner instance that is used to find AIs
 };
 
 #else /* ENABLE_AI */
diff --git a/src/ai/ai_config.cpp b/src/ai/ai_config.cpp
index aab8b1f18..1c50a1d01 100644
--- a/src/ai/ai_config.cpp
+++ b/src/ai/ai_config.cpp
@@ -48,7 +48,6 @@ void AIConfig::ChangeAI(const char *name, int version, bool force_exact_match, b
 		}
 		this->AddRandomDeviation();
 	}
-
 }
 
 AIConfig::AIConfig(const AIConfig *config)
diff --git a/src/ai/ai_config.hpp b/src/ai/ai_config.hpp
index 98e98263c..c5b7c7482 100644
--- a/src/ai/ai_config.hpp
+++ b/src/ai/ai_config.hpp
@@ -18,8 +18,12 @@
 #include "../core/string_compare_type.hpp"
 #include "../company_type.h"
 
+/**
+ * AI settings for one company slot.
+ */
 class AIConfig {
 private:
+	/** List with name=>value pairs of all AI-specific settings */
 	typedef std::map<const char *, int, StringCompare> SettingValueList;
 
 public:
@@ -30,7 +34,14 @@ public:
 		config_list(NULL),
 		is_random_ai(false)
 	{}
+
+	/**
+	 * Create a new AI config that is a copy of an existing config.
+	 * @param config The object to copy.
+	 */
 	AIConfig(const AIConfig *config);
+
+	/** Delete an AI configuration. */
 	~AIConfig();
 
 	/**
@@ -61,8 +72,10 @@ public:
 	 */
 	const AIConfigItemList *GetConfigList();
 
-	/* Where to get the config from, either default (depends on current game
-	 * mode) or force either newgame or normal */
+	/**
+	 * Where to get the config from, either default (depends on current game
+	 * mode) or force either newgame or normal
+	 */
 	enum AISettingSource {
 		AISS_DEFAULT,       ///< Get the AI config from the current game mode
 		AISS_FORCE_NEWGAME, ///< Get the newgame AI config
@@ -131,12 +144,12 @@ public:
 	void SettingsToString(char *string, size_t size) const;
 
 private:
-	const char *name;
-	int version;
-	class AIInfo *info;
-	SettingValueList settings;
-	AIConfigItemList *config_list;
-	bool is_random_ai;
+	const char *name;              //!< Name of the AI
+	int version;                   //!< Version of the AI
+	class AIInfo *info;            //!< AIInfo object for related to this AI version
+	SettingValueList settings;     //!< List with all setting=>value pairs that are configure for this AI
+	AIConfigItemList *config_list; //!< List with all settings defined by this AI
+	bool is_random_ai;             //!< True if the AI in this slot was randomly chosen.
 };
 
 #endif /* ENABLE_AI */
diff --git a/src/ai/ai_core.cpp b/src/ai/ai_core.cpp
index ab950ef06..b6c072500 100644
--- a/src/ai/ai_core.cpp
+++ b/src/ai/ai_core.cpp
@@ -229,6 +229,13 @@
 	event->Release();
 }
 
+/**
+ * DoCommand callback function for all commands executed by AIs.
+ * @param result The result of the command.
+ * @param tile The tile on which the command was executed.
+ * @param p1 p1 as given to DoCommandPInternal.
+ * @param p2 p2 as given to DoCommandPInternal.
+ */
 void CcAI(const CommandCost &result, TileIndex tile, uint32 p1, uint32 p2)
 {
 	AIObject::SetLastCommandRes(result.Succeeded());
diff --git a/src/ai/ai_gui.cpp b/src/ai/ai_gui.cpp
index e3f4c53bf..5a404b9d7 100644
--- a/src/ai/ai_gui.cpp
+++ b/src/ai/ai_gui.cpp
@@ -695,8 +695,8 @@ 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;
 
diff --git a/src/ai/ai_info.cpp b/src/ai/ai_info.cpp
index 29abb7e15..5ccd934fd 100644
--- a/src/ai/ai_info.cpp
+++ b/src/ai/ai_info.cpp
@@ -21,6 +21,7 @@
 #include "../debug.h"
 #include "../rev.h"
 
+/** Configuration for AI start date, every AI has this setting. */
 AIConfigItem _start_date_config = {
 	"start_date",
 	"The amount of days after the start of the last AI, this AI will start (give or take).",
@@ -50,6 +51,10 @@ AILibrary::~AILibrary()
 	return 0;
 }
 
+/**
+ * Check if the API version provided by the AI is supported.
+ * @param api_version The API version as provided by the AI.
+ */
 static bool CheckAPIVersion(const char *api_version)
 {
 	return strcmp(api_version, "0.7") == 0 || strcmp(api_version, "1.0") == 0 || strcmp(api_version, "1.1") == 0;
diff --git a/src/ai/ai_info.hpp b/src/ai/ai_info.hpp
index 9ef6e3df1..2f6edad01 100644
--- a/src/ai/ai_info.hpp
+++ b/src/ai/ai_info.hpp
@@ -18,15 +18,17 @@
 #include "../core/smallmap_type.hpp"
 #include "../script/script_info.hpp"
 
+/** Bitmask of flags for AI settings. */
 enum AIConfigFlags {
-	AICONFIG_NONE    = 0x0,
+	AICONFIG_NONE    = 0x0, //!< No flags set.
 	AICONFIG_RANDOM  = 0x1, //!< When randomizing the AI, pick any value between min_value and max_value when on custom difficulty setting.
 	AICONFIG_BOOLEAN = 0x2, //!< This value is a boolean (either 0 (false) or 1 (true) ).
 	AICONFIG_INGAME  = 0x4, //!< This setting can be changed while the AI is running.
 };
 
-typedef SmallMap<int, char *> LabelMapping;
+typedef SmallMap<int, char *> LabelMapping; //!< Map-type used to map the setting numbers to labels.
 
+/** Info about a single AI setting. */
 struct AIConfigItem {
 	const char *name;        //!< The name of the configuration setting.
 	const char *description; //!< The description of the configuration setting.
@@ -44,8 +46,9 @@ struct AIConfigItem {
 
 extern AIConfigItem _start_date_config;
 
-typedef std::list<AIConfigItem> AIConfigItemList;
+typedef std::list<AIConfigItem> AIConfigItemList; //!< List of AIConfig items.
 
+/** Base class that holds some basic information about AIs and AI libraries. */
 class AIFileInfo : public ScriptFileInfo {
 public:
 	/**
@@ -54,9 +57,10 @@ public:
 	static SQInteger Constructor(HSQUIRRELVM vm, AIFileInfo *info);
 
 protected:
-	class AIScanner *base;
+	class AIScanner *base; //!< AIScanner object that was used to scan this AI (library) info.
 };
 
+/** All static information from an AI like name, version, etc. */
 class AIInfo : public AIFileInfo {
 public:
 	static const char *GetClassName() { return "AIInfo"; }
@@ -68,6 +72,10 @@ public:
 	 * Create an AI, using this AIInfo as start-template.
 	 */
 	static SQInteger Constructor(HSQUIRRELVM vm);
+
+	/**
+	 * Create a dummy-AI.
+	 */
 	static SQInteger DummyConstructor(HSQUIRRELVM vm);
 
 	/**
@@ -116,12 +124,13 @@ public:
 	const char *GetAPIVersion() const { return this->api_version; }
 
 private:
-	AIConfigItemList config_list;
-	int min_loadable_version;
-	bool use_as_random;
-	const char *api_version;
+	AIConfigItemList config_list; //!< List of settings from this AI.
+	int min_loadable_version;     //!< The AI can load savegame data if the version is equal or greater than this.
+	bool use_as_random;           //!< Should this AI be used when the user wants a "random AI"?
+	const char *api_version;      //!< API version used by this AI.
 };
 
+/** All static information from an AI library like name, version, etc. */
 class AILibrary : public AIFileInfo {
 public:
 	AILibrary() : AIFileInfo(), category(NULL) {};
@@ -132,6 +141,11 @@ public:
 	 */
 	static SQInteger Constructor(HSQUIRRELVM vm);
 
+	/**
+	 * Import a library in the current AI. This function can be used by AIs
+	 * by calling import.
+	 * @param vm The squirrel vm of the calling AI.
+	 */
 	static SQInteger Import(HSQUIRRELVM vm);
 
 	/**
@@ -140,7 +154,7 @@ public:
 	const char *GetCategory() const { return this->category; }
 
 private:
-	const char *category;
+	const char *category; //!< The category this library is in.
 };
 
 #endif /* ENABLE_AI */
diff --git a/src/ai/ai_info_dummy.cpp b/src/ai/ai_info_dummy.cpp
index f38832310..f706110f7 100644
--- a/src/ai/ai_info_dummy.cpp
+++ b/src/ai/ai_info_dummy.cpp
@@ -25,6 +25,7 @@
  *  to select manual. It is a fail-over in case no AIs are available.
  */
 
+/** info.nut for the dummy AI. */
 const SQChar _dummy_script_info[] = _SC("                                                       \n\
 class DummyAI extends AIInfo {                                                                  \n\
   function GetAuthor()      { return \"OpenTTD NoAI Developers Team\"; }                        \n\
@@ -39,6 +40,7 @@ class DummyAI extends AIInfo {
 RegisterDummyAI(DummyAI());                                                                     \n\
 ");
 
+/** Run the dummy info.nut. */
 void AI_CreateAIInfoDummy(HSQUIRRELVM vm)
 {
 	sq_pushroottable(vm);
@@ -54,6 +56,7 @@ void AI_CreateAIInfoDummy(HSQUIRRELVM vm)
 	NOT_REACHED();
 }
 
+/** Run the dummy AI and let it generate an error message. */
 void AI_CreateAIDummy(HSQUIRRELVM vm)
 {
 	/* We want to translate the error message.
diff --git a/src/ai/ai_instance.cpp b/src/ai/ai_instance.cpp
index 4a0924995..a1dc69d07 100644
--- a/src/ai/ai_instance.cpp
+++ b/src/ai/ai_instance.cpp
@@ -87,6 +87,11 @@ AIStorage::~AIStorage()
 	if (log_data != NULL) AILog::FreeLogPointer();
 }
 
+/**
+ * Callback called by squirrel when an AI uses "print" and for error messages.
+ * @param error_msg Is this an error message?
+ * @param message The actual message text.
+ */
 static void PrintFunc(bool error_msg, const SQChar *message)
 {
 	/* Convert to OpenTTD internal capable string */
@@ -453,8 +458,9 @@ enum SQSaveLoadType {
 	SQSL_ARRAY_TABLE_END = 0xFF, ///< Marks the end of an array or table, no data follows.
 };
 
-static byte _ai_sl_byte;
+static byte _ai_sl_byte; //!< Used as source/target by the AI saveload code to store/load a single byte.
 
+/** SaveLoad array that saves/loads exactly one byte. */
 static const SaveLoad _ai_byte[] = {
 	SLEG_VAR(_ai_sl_byte, SLE_UINT8),
 	SLE_END()
diff --git a/src/ai/ai_instance.hpp b/src/ai/ai_instance.hpp
index f046aa86c..8d838f057 100644
--- a/src/ai/ai_instance.hpp
+++ b/src/ai/ai_instance.hpp
@@ -29,12 +29,21 @@ public:
 		callback(callback)
 	{}
 
+	/**
+	 * Get the amount ot ticks the AI should be suspended.
+	 * @return The amount of AI ticks to suspend the AI.
+	 */
 	int GetSuspendTime() { return time; }
+
+	/**
+	 * Get the callback to call when the AI can run again.
+	 * @return The callback function to run.
+	 */
 	AISuspendCallbackProc *GetSuspendCallback() { return callback; }
 
 private:
-	int time;
-	AISuspendCallbackProc *callback;
+	int time;                        //!< Amount of ticks to suspend the AI.
+	AISuspendCallbackProc *callback; //!< Callback function to call when the AI can run again.
 };
 
 /**
@@ -52,6 +61,7 @@ private:
 	const char *msg;
 };
 
+/** Runtime information about an AI like a pointer to the squirrel vm and the current state. */
 class AIInstance {
 public:
 	friend class AIObject;
@@ -145,16 +155,16 @@ public:
 	 */
 	void Suspend();
 private:
-	class AIController *controller;
-	class AIStorage *storage;
-	class Squirrel *engine;
-	SQObject *instance;
-
-	bool is_started;
-	bool is_dead;
-	bool is_save_data_on_stack;
-	int suspend;
-	AISuspendCallbackProc *callback;
+	class AIController *controller;  //!< The AI main class.
+	class AIStorage *storage;        //!< Some global information for each running AI.
+	class Squirrel *engine;          //!< A wrapper around the squirrel vm.
+	SQObject *instance;              //!< Squirrel-pointer to the AI main class.
+
+	bool is_started;                 //!< Is the AIs constructor executed?
+	bool is_dead;                    //!< True if the AI has been stopped.
+	bool is_save_data_on_stack;      //!< Is the save data still on the squirrel stack?
+	int suspend;                     //!< The amount of ticks to suspend this AI before it's allowed to continue.
+	AISuspendCallbackProc *callback; //!< Callback that should be called in the next tick the AI runs.
 
 	/**
 	 * Register all API functions to the VM.
diff --git a/src/ai/ai_scanner.hpp b/src/ai/ai_scanner.hpp
index 3a4fdc034..f88555699 100644
--- a/src/ai/ai_scanner.hpp
+++ b/src/ai/ai_scanner.hpp
@@ -18,6 +18,9 @@
 #include "ai.hpp"
 #include <map>
 
+/**
+ * Class that scans for available AIs.
+ */
 class AIScanner : public ScriptScanner {
 public:
 	AIScanner();