dave/openttd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

(svn r22396) -Document: some AI doxygen stuff

Browse Source
This commit is contained in:
rubidium
2011-05-01 09:24:19 +00:00
parent 0573c8bd07
commit 2c1555b13c
18 changed files with 199 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
src/ai/api/ai_accounting.hpp
View File

@@ -62,7 +62,7 @@ public:
void ResetCosts();
private:
Money last_costs;
Money last_costs; ///< The last cost we did return.
};
#endif /* AI_ACCOUNTING_HPP */

12
src/ai/api/ai_bridge.cpp
View File

@@ -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()

2
src/ai/api/ai_changelog.hpp
View File

@@ -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.

8
src/ai/api/ai_controller.hpp
View File

@@ -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.

8
src/ai/api/ai_error.hpp
View File

@@ -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 */

3
src/ai/api/ai_event.cpp
View File

@@ -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()

59
src/ai/api/ai_event_types.hpp
View File

@@ -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 */

4
src/ai/api/ai_execmode.hpp
View File

@@ -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:
/**

81
src/ai/api/ai_list.cpp
View File

@@ -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;
}
};

4
src/ai/api/ai_object.cpp
View File

@@ -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();

1
src/ai/api/ai_object.hpp
View File

@@ -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();

8
src/ai/api/ai_order.cpp
View File

@@ -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;

4
src/ai/api/ai_testmode.hpp
View File

@@ -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:
/**

12
src/ai/api/ai_tunnel.cpp
View File

@@ -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()