From 70c7ec30b1c10bc4502a14e45555fff7a310fca4 Mon Sep 17 00:00:00 2001 From: rubidium Date: Sun, 1 May 2011 09:24:19 +0000 Subject: [PATCH] (svn r22396) -Document: some AI doxygen stuff --- src/ai/ai_gui.cpp | 69 +++++++++++++++++++---------- src/ai/ai_info.hpp | 4 ++ src/ai/ai_instance.hpp | 20 ++++++++- src/ai/ai_scanner.hpp | 14 +++--- src/ai/api/ai_accounting.hpp | 2 +- src/ai/api/ai_bridge.cpp | 12 +++++- src/ai/api/ai_changelog.hpp | 2 +- src/ai/api/ai_controller.hpp | 8 ++-- src/ai/api/ai_error.hpp | 8 ++-- src/ai/api/ai_event.cpp | 3 +- src/ai/api/ai_event_types.hpp | 59 +++++++++++++------------ src/ai/api/ai_execmode.hpp | 4 +- src/ai/api/ai_list.cpp | 81 +++++++++++++++++++---------------- src/ai/api/ai_object.cpp | 4 ++ src/ai/api/ai_object.hpp | 1 + src/ai/api/ai_order.cpp | 8 ++-- src/ai/api/ai_testmode.hpp | 4 +- src/ai/api/ai_tunnel.cpp | 12 +++++- 18 files changed, 199 insertions(+), 116 deletions(-) diff --git a/src/ai/ai_gui.cpp b/src/ai/ai_gui.cpp index 1f57b8ebcc..3fb36a09db 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 ace456a79c..9362374180 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 9a427c8c61..718531feb0 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 fee16d6081..f3d0776c6d 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 AILibraryList; + typedef std::map 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 1d4fc90857..976513269c 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 a051e85a25..8550b3df5b 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 8cebbb3e39..d9cc76e3a7 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 03dd77ef42..2ab7c245b0 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 LoadedLibraryList; + typedef std::map 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 c2dd8ba950..44e4573d44 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 AIErrorMap; - typedef std::map AIErrorMapString; + typedef std::map AIErrorMap; ///< The type for mapping between error (internal OpenTTD) StringID to the AI error type. + typedef std::map 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 32edd1a0ee..d659aea60f 100644 --- a/src/ai/api/ai_event.cpp +++ b/src/ai/api/ai_event.cpp @@ -14,8 +14,9 @@ #include +/** The queue of events for an AI. */ struct AIEventData { - std::queue stack; + std::queue 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 51bfa6cd96..41cbc19654 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 f5d2a53984..569cc65260 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 e41b7e69c0..2188d66742 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 f2ddbebaef..53f09d11ae 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 06d0f9edb2..e928bef23f 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 7522917516..0c646f0520 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 a5596727e4..c82ce78914 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 59055af2fc..99aec30c4a 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()