From 70c7ec30b1c10bc4502a14e45555fff7a310fca4 Mon Sep 17 00:00:00 2001 From: rubidium Date: Sun, 1 May 2011 09:24:19 +0000 Subject: (svn r22396) -Document: some AI doxygen stuff --- 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 +++++-- 14 files changed, 120 insertions(+), 88 deletions(-) (limited to 'src/ai/api') 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 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 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 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 32edd1a0e..d659aea60 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 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() -- cgit v1.2.3-54-g00ecf