Mercurial > hg > openttd
changeset 15608:1dd01996756e draft
(svn r20271) -Doc: add doxygen comments to several items under src/ai/
| author | yexo <yexo@openttd.org> |
|---|---|
| date | Sat, 31 Jul 2010 22:16:34 +0000 |
| parents | 698b1047e2a2 |
| children | 7ec34cccb731 |
| files | src/ai/ai.hpp src/ai/ai_config.cpp src/ai/ai_config.hpp src/ai/ai_core.cpp src/ai/ai_gui.cpp src/ai/ai_info.cpp src/ai/ai_info.hpp src/ai/ai_info_dummy.cpp src/ai/ai_instance.cpp src/ai/ai_instance.hpp src/ai/ai_scanner.hpp |
| diffstat | 11 files changed, 109 insertions(+), 35 deletions(-) [+] |
line wrap: on
line diff
--- 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 @@ */ 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 */
--- a/src/ai/ai_config.cpp +++ b/src/ai/ai_config.cpp @@ -48,7 +48,6 @@ } this->AddRandomDeviation(); } - } AIConfig::AIConfig(const AIConfig *config)
--- 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 @@ 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 @@ */ 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 @@ 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 */
--- 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());
--- a/src/ai/ai_gui.cpp +++ b/src/ai/ai_gui.cpp @@ -695,8 +695,8 @@ * 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;
--- 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 @@ 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;
--- 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 @@ 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 @@ 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 @@ * 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 @@ 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 @@ */ 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 @@ const char *GetCategory() const { return this->category; } private: - const char *category; + const char *category; //!< The category this library is in. }; #endif /* ENABLE_AI */
--- 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 @@ RegisterDummyAI(DummyAI()); \n\ "); +/** Run the dummy info.nut. */ void AI_CreateAIInfoDummy(HSQUIRRELVM vm) { sq_pushroottable(vm); @@ -54,6 +56,7 @@ 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.
--- a/src/ai/ai_instance.cpp +++ b/src/ai/ai_instance.cpp @@ -87,6 +87,11 @@ 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 @@ 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()
--- a/src/ai/ai_instance.hpp +++ b/src/ai/ai_instance.hpp @@ -29,12 +29,21 @@ 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 @@ 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 @@ */ void Suspend(); private: - class AIController *controller; - class AIStorage *storage; - class Squirrel *engine; - SQObject *instance; + 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; - bool is_dead; - bool is_save_data_on_stack; - int suspend; - AISuspendCallbackProc *callback; + 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.