Mercurial > hg > openttd
changeset 17107:b6e74a185e03 draft
(svn r21844) -Codechange: move documentation towards the code to make it more likely to be updates [a-c].
author | rubidium <rubidium@openttd.org> |
---|---|
date | Tue, 18 Jan 2011 22:17:15 +0000 |
parents | 49e51c1b1b5f |
children | 5ae3089defb2 |
files | src/aircraft.h src/aircraft_cmd.cpp src/autoreplace.cpp src/autoreplace_func.h src/autoreplace_gui.h src/base_media_base.h src/base_media_func.h src/bridge_map.cpp src/bridge_map.h src/cargopacket.cpp src/cargopacket.h src/cheat.cpp src/cheat_func.h src/command_func.h src/crashlog.cpp src/crashlog.h |
diffstat | 16 files changed, 250 insertions(+), 316 deletions(-) [+] |
line wrap: on
line diff
--- a/src/aircraft.h +++ b/src/aircraft.h @@ -26,31 +26,9 @@ }; -/** - * Handle Aircraft specific tasks when an Aircraft enters a hangar - * @param *v Vehicle that enters the hangar - */ void HandleAircraftEnterHangar(Aircraft *v); - -/** - * Get the size of the sprite of an aircraft sprite heading west (used for lists) - * @param engine The engine to get the sprite from - * @param width The width of the sprite - * @param height The height of the sprite - */ void GetAircraftSpriteSize(EngineID engine, uint &width, uint &height); - -/** - * Updates the status of the Aircraft heading or in the station - * @param st Station been updated - */ void UpdateAirplanesOnNewStation(const Station *st); - -/** - * Update cached values of an aircraft. - * Currently caches callback 36 max speed. - * @param v Vehicle - */ void UpdateAircraftCache(Aircraft *v); void AircraftLeaveHangar(Aircraft *v);
--- a/src/aircraft_cmd.cpp +++ b/src/aircraft_cmd.cpp @@ -533,6 +533,11 @@ } +/** + * Update cached values of an aircraft. + * Currently caches callback 36 max speed. + * @param v Vehicle + */ void UpdateAircraftCache(Aircraft *v) { uint max_speed = GetVehicleProperty(v, PROP_AIRCRAFT_SPEED, 0);
--- a/src/autoreplace.cpp +++ b/src/autoreplace.cpp @@ -33,6 +33,11 @@ return NULL; } +/** + * Remove all engine replacement settings for the company. + * @param erl The renewlist for a given company. + * @return The new renewlist for the company. + */ void RemoveAllEngineReplacement(EngineRenewList *erl) { EngineRenew *er = (EngineRenew *)(*erl); @@ -46,6 +51,14 @@ *erl = NULL; // Empty list } +/** + * Retrieve the engine replacement in a given renewlist for an original engine type. + * @param erl The renewlist to search in. + * @param engine Engine type to be replaced. + * @param group The group related to this replacement. + * @return The engine type to replace with, or INVALID_ENGINE if no + * replacement is in the list. + */ EngineID EngineReplacement(EngineRenewList erl, EngineID engine, GroupID group) { const EngineRenew *er = GetEngineReplacement(erl, engine, group); @@ -56,6 +69,15 @@ return er == NULL ? INVALID_ENGINE : er->to; } +/** + * Add an engine replacement to the given renewlist. + * @param erl The renewlist to add to. + * @param old_engine The original engine type. + * @param new_engine The replacement engine type. + * @param group The group related to this replacement. + * @param flags The calling command flags. + * @return 0 on success, CMD_ERROR on failure. + */ CommandCost AddEngineReplacement(EngineRenewList *erl, EngineID old_engine, EngineID new_engine, GroupID group, DoCommandFlag flags) { /* Check if the old vehicle is already in the list */ @@ -79,6 +101,14 @@ return CommandCost(); } +/** + * Remove an engine replacement from a given renewlist. + * @param erl The renewlist from which to remove the replacement + * @param engine The original engine type. + * @param group The group related to this replacement. + * @param flags The calling command flags. + * @return 0 on success, CMD_ERROR on failure. + */ CommandCost RemoveEngineReplacement(EngineRenewList *erl, EngineID engine, GroupID group, DoCommandFlag flags) { EngineRenew *er = (EngineRenew *)(*erl);
--- a/src/autoreplace_func.h +++ b/src/autoreplace_func.h @@ -17,42 +17,9 @@ #include "engine_type.h" #include "group_type.h" -/** - * Remove all engine replacement settings for the company. - * @param erl The renewlist for a given company. - * @return The new renewlist for the company. - */ void RemoveAllEngineReplacement(EngineRenewList *erl); - -/** - * Retrieve the engine replacement in a given renewlist for an original engine type. - * @param erl The renewlist to search in. - * @param engine Engine type to be replaced. - * @param group The group related to this replacement. - * @return The engine type to replace with, or INVALID_ENGINE if no - * replacement is in the list. - */ EngineID EngineReplacement(EngineRenewList erl, EngineID engine, GroupID group); - -/** - * Add an engine replacement to the given renewlist. - * @param erl The renewlist to add to. - * @param old_engine The original engine type. - * @param new_engine The replacement engine type. - * @param group The group related to this replacement. - * @param flags The calling command flags. - * @return 0 on success, CMD_ERROR on failure. - */ CommandCost AddEngineReplacement(EngineRenewList *erl, EngineID old_engine, EngineID new_engine, GroupID group, DoCommandFlag flags); - -/** - * Remove an engine replacement from a given renewlist. - * @param erl The renewlist from which to remove the replacement - * @param engine The original engine type. - * @param group The group related to this replacement. - * @param flags The calling command flags. - * @return 0 on success, CMD_ERROR on failure. - */ CommandCost RemoveEngineReplacement(EngineRenewList *erl, EngineID engine, GroupID group, DoCommandFlag flags); /**
--- a/src/autoreplace_gui.h +++ b/src/autoreplace_gui.h @@ -16,10 +16,6 @@ #include "group_type.h" #include "vehicle_type.h" -/** - * When an engine is made buildable or is removed from being buildable, add/remove it from the build/autoreplace lists - * @param type The type of engine - */ void AddRemoveEngineFromAutoreplaceAndBuildWindows(VehicleType type); void InvalidateAutoreplaceWindow(EngineID e, GroupID id_g); void ShowReplaceGroupVehicleWindow(GroupID group, VehicleType veh);
--- a/src/base_media_base.h +++ b/src/base_media_base.h @@ -104,14 +104,6 @@ return Tnum_files - this->valid_files; } - /** - * Read the set information from a loaded ini. - * @param ini the ini to read from - * @param path the path to this ini file (for filenames) - * @param full_filename the full filename of the loaded file (for error reporting purposes) - * @param allow_empty_filename empty filenames are valid - * @return true if loading was successful. - */ bool FillSetDetails(IniFile *ini, const char *path, const char *full_filename, bool allow_empty_filename = true); /** @@ -177,42 +169,11 @@ return fs.Scan(GetExtension(), Tbase_set::SUBDIR, Tbase_set::SUBDIR != GM_DIR); } - /** - * Set the set to be used. - * @param name of the set to use - * @return true if it could be loaded - */ static bool SetSet(const char *name); - - /** - * Returns a list with the sets. - * @param p where to print to - * @param last the last character to print to - * @return the last printed character - */ static char *GetSetsList(char *p, const char *last); - - /** - * Count the number of available graphics sets. - * @return the number of sets - */ static int GetNumSets(); - - /** - * Get the index of the currently active graphics set - * @return the current set's index - */ static int GetIndexOfUsedSet(); - - /** - * Get the name of the graphics set at the specified index - * @return the name of the set - */ static const Tbase_set *GetSet(int index); - /** - * Return the used set. - * @return the used set. - */ static const Tbase_set *GetUsedSet(); /**
--- a/src/base_media_func.h +++ b/src/base_media_func.h @@ -31,6 +31,14 @@ return false; \ } +/** + * Read the set information from a loaded ini. + * @param ini the ini to read from + * @param path the path to this ini file (for filenames) + * @param full_filename the full filename of the loaded file (for error reporting purposes) + * @param allow_empty_filename empty filenames are valid + * @return true if loading was successful. + */ template <class T, size_t Tnum_files, Subdirectory Tsubdir> bool BaseSet<T, Tnum_files, Tsubdir>::FillSetDetails(IniFile *ini, const char *path, const char *full_filename, bool allow_empty_filename) { @@ -208,6 +216,11 @@ return ret; } +/** + * Set the set to be used. + * @param name of the set to use + * @return true if it could be loaded + */ template <class Tbase_set> /* static */ bool BaseMedia<Tbase_set>::SetSet(const char *name) { @@ -229,6 +242,12 @@ return false; } +/** + * Returns a list with the sets. + * @param p where to print to + * @param last the last character to print to + * @return the last printed character + */ template <class Tbase_set> /* static */ char *BaseMedia<Tbase_set>::GetSetsList(char *p, const char *last) { @@ -293,6 +312,10 @@ #endif /* ENABLE_NETWORK */ +/** + * Count the number of available graphics sets. + * @return the number of sets + */ template <class Tbase_set> /* static */ int BaseMedia<Tbase_set>::GetNumSets() { @@ -304,6 +327,10 @@ return n; } +/** + * Get the index of the currently active graphics set + * @return the current set's index + */ template <class Tbase_set> /* static */ int BaseMedia<Tbase_set>::GetIndexOfUsedSet() { @@ -316,6 +343,10 @@ return -1; } +/** + * Get the name of the graphics set at the specified index + * @return the name of the set + */ template <class Tbase_set> /* static */ const Tbase_set *BaseMedia<Tbase_set>::GetSet(int index) { @@ -327,6 +358,10 @@ error("Base" SET_TYPE "::GetSet(): index %d out of range", index); } +/** + * Return the used set. + * @return the used set. + */ template <class Tbase_set> /* static */ const Tbase_set *BaseMedia<Tbase_set>::GetUsedSet() {
--- a/src/bridge_map.cpp +++ b/src/bridge_map.cpp @@ -32,24 +32,41 @@ } +/** + * Finds the northern end of a bridge starting at a middle tile + * @param t the bridge tile to find the bridge ramp for + */ TileIndex GetNorthernBridgeEnd(TileIndex t) { return GetBridgeEnd(t, ReverseDiagDir(AxisToDiagDir(GetBridgeAxis(t)))); } +/** + * Finds the southern end of a bridge starting at a middle tile + * @param t the bridge tile to find the bridge ramp for + */ TileIndex GetSouthernBridgeEnd(TileIndex t) { return GetBridgeEnd(t, AxisToDiagDir(GetBridgeAxis(t))); } +/** + * Starting at one bridge end finds the other bridge end + * @param t the bridge ramp tile to find the other bridge ramp for + */ TileIndex GetOtherBridgeEnd(TileIndex tile) { assert(IsBridgeTile(tile)); return GetBridgeEnd(tile, GetTunnelBridgeDirection(tile)); } +/** + * Get the height ('z') of a bridge in pixels. + * @param tile the bridge ramp tile to get the bridge height from + * @return the height of the bridge in pixels + */ uint GetBridgeHeight(TileIndex t) { uint h;
--- a/src/bridge_map.h +++ b/src/bridge_map.h @@ -85,30 +85,10 @@ return (Axis)(GB(_m[t].m6, 6, 2) - 1); } -/** - * Finds the northern end of a bridge starting at a middle tile - * @param t the bridge tile to find the bridge ramp for - */ TileIndex GetNorthernBridgeEnd(TileIndex t); - -/** - * Finds the southern end of a bridge starting at a middle tile - * @param t the bridge tile to find the bridge ramp for - */ TileIndex GetSouthernBridgeEnd(TileIndex t); - - -/** - * Starting at one bridge end finds the other bridge end - * @param t the bridge ramp tile to find the other bridge ramp for - */ TileIndex GetOtherBridgeEnd(TileIndex t); -/** - * Get the height ('z') of a bridge in pixels. - * @param tile the bridge ramp tile to get the bridge height from - * @return the height of the bridge in pixels - */ uint GetBridgeHeight(TileIndex tile); /**
--- a/src/cargopacket.cpp +++ b/src/cargopacket.cpp @@ -25,14 +25,26 @@ _cargopacket_pool.CleanPool(); } +/** + * Create a new packet for savegame loading. + */ CargoPacket::CargoPacket() { this->source_type = ST_INDUSTRY; this->source_id = INVALID_SOURCE; } -/* NOTE: We have to zero memory ourselves here because we are using a 'new' - * that, in contrary to all other pools, does not memset to 0. */ +/** + * Creates a new cargo packet + * @param source the source station of the packet + * @param source_xy the source location of the packet + * @param count the number of cargo entities to put in this packet + * @param source_type the 'type' of source the packet comes from (for subsidies) + * @param source_id the actual source of the packet (for subsidies) + * @pre count != 0 + * @note We have to zero memory ourselves here because we are using a 'new' + * that, in contrary to all other pools, does not memset to 0. + */ CargoPacket::CargoPacket(StationID source, TileIndex source_xy, uint16 count, SourceType source_type, SourceID source_id) : feeder_share(0), count(count), @@ -46,6 +58,18 @@ this->source_type = source_type; } +/** + * Creates a new cargo packet. Initializes the fields that cannot be changed later. + * Used when loading or splitting packets. + * @param count the number of cargo entities to put in this packet + * @param days_in_transit number of days the cargo has been in transit + * @param source the station the cargo was initially loaded + * @param source_xy the station location the cargo was initially loaded + * @param loaded_at_xy the location the cargo was loaded last + * @param feeder_share feeder share the packet has already accumulated + * @param source_type the 'type' of source the packet comes from (for subsidies) + * @param source_id the actual source of the packet (for subsidies) + */ CargoPacket::CargoPacket(uint16 count, byte days_in_transit, StationID source, TileIndex source_xy, TileIndex loaded_at_xy, Money feeder_share, SourceType source_type, SourceID source_id) : feeder_share(feeder_share), count(count), @@ -90,6 +114,7 @@ * */ +/** Destroy it ("frees" all cargo packets) */ template <class Tinst> CargoList<Tinst>::~CargoList() { @@ -98,6 +123,11 @@ } } +/** + * Update the cached values to reflect the removal of this packet. + * Decreases count and days_in_transit + * @param cp Packet to be removed from cache + */ template <class Tinst> void CargoList<Tinst>::RemoveFromCache(const CargoPacket *cp) { @@ -105,6 +135,11 @@ this->cargo_days_in_transit -= cp->days_in_transit * cp->count; } +/** + * Update the cache to reflect adding of this packet. + * Increases count and days_in_transit + * @param cp a new packet to be inserted + */ template <class Tinst> void CargoList<Tinst>::AddToCache(const CargoPacket *cp) { @@ -112,6 +147,13 @@ this->cargo_days_in_transit += cp->days_in_transit * cp->count; } +/** + * Appends the given cargo packet + * @warning After appending this packet may not exist anymore! + * @note Do not use the cargo packet anymore after it has been appended to this CargoList! + * @param cp the cargo packet to add + * @pre cp != NULL + */ template <class Tinst> void CargoList<Tinst>::Append(CargoPacket *cp) { @@ -134,6 +176,11 @@ } +/** + * Truncates the cargo in this list to the given amount. It leaves the + * first count cargo entities and removes the rest. + * @param max_remaining the maximum amount of entities to be in the list after the command + */ template <class Tinst> void CargoList<Tinst>::Truncate(uint max_remaining) { @@ -161,6 +208,27 @@ } } +/** + * Moves the given amount of cargo to another list. + * Depending on the value of mta the side effects of this function differ: + * - MTA_FINAL_DELIVERY: destroys the packets that do not originate from a specific station + * - MTA_CARGO_LOAD: sets the loaded_at_xy value of the moved packets + * - MTA_TRANSFER: just move without side effects + * - MTA_UNLOAD: just move without side effects + * @param dest the destination to move the cargo to + * @param count the amount of cargo entities to move + * @param mta how to handle the moving (side effects) + * @param data Depending on mta the data of this variable differs: + * - MTA_FINAL_DELIVERY - station ID of packet's origin not to remove + * - MTA_CARGO_LOAD - station's tile index of load + * - MTA_TRANSFER - unused + * - MTA_UNLOAD - unused + * @param payment The payment helper + * + * @pre mta == MTA_FINAL_DELIVERY || dest != NULL + * @pre mta == MTA_UNLOAD || mta == MTA_CARGO_LOAD || payment != NULL + * @return true if there are still packets that might be moved from this cargo list + */ template <class Tinst> template <class Tother_inst> bool CargoList<Tinst>::MoveTo(Tother_inst *dest, uint max_move, MoveToAction mta, CargoPayment *payment, uint data) @@ -240,6 +308,7 @@ return it != packets.end(); } +/** Invalidates the cached data and rebuild it */ template <class Tinst> void CargoList<Tinst>::InvalidateCache() { @@ -252,18 +321,31 @@ } +/** + * Update the cached values to reflect the removal of this packet. + * Decreases count, feeder share and days_in_transit + * @param cp Packet to be removed from cache + */ void VehicleCargoList::RemoveFromCache(const CargoPacket *cp) { this->feeder_share -= cp->feeder_share; this->Parent::RemoveFromCache(cp); } +/** + * Update the cache to reflect adding of this packet. + * Increases count, feeder share and days_in_transit + * @param cp a new packet to be inserted + */ void VehicleCargoList::AddToCache(const CargoPacket *cp) { this->feeder_share += cp->feeder_share; this->Parent::AddToCache(cp); } +/** + * Ages the all cargo in this list + */ void VehicleCargoList::AgeCargo() { for (ConstIterator it(this->packets.begin()); it != this->packets.end(); it++) { @@ -276,6 +358,7 @@ } } +/** Invalidates the cached data and rebuild it */ void VehicleCargoList::InvalidateCache() { this->feeder_share = 0;
--- a/src/cargopacket.h +++ b/src/cargopacket.h @@ -55,34 +55,8 @@ /** Maximum number of items in a single cargo packet. */ static const uint16 MAX_COUNT = UINT16_MAX; - /** - * Create a new packet for savegame loading. - */ CargoPacket(); - - /** - * Creates a new cargo packet - * @param source the source station of the packet - * @param source_xy the source location of the packet - * @param count the number of cargo entities to put in this packet - * @param source_type the 'type' of source the packet comes from (for subsidies) - * @param source_id the actual source of the packet (for subsidies) - * @pre count != 0 - */ CargoPacket(StationID source, TileIndex source_xy, uint16 count, SourceType source_type, SourceID source_id); - - /** - * Creates a new cargo packet. Initializes the fields that cannot be changed later. - * Used when loading or splitting packets. - * @param count the number of cargo entities to put in this packet - * @param days_in_transit number of days the cargo has been in transit - * @param source the station the cargo was initially loaded - * @param source_xy the station location the cargo was initially loaded - * @param loaded_at_xy the location the cargo was loaded last - * @param feeder_share feeder share the packet has already accumulated - * @param source_type the 'type' of source the packet comes from (for subsidies) - * @param source_id the actual source of the packet (for subsidies) - */ CargoPacket(uint16 count, byte days_in_transit, StationID source, TileIndex source_xy, TileIndex loaded_at_xy, Money feeder_share = 0, SourceType source_type = ST_INDUSTRY, SourceID source_id = INVALID_SOURCE); /** Destroy the packet */ @@ -211,24 +185,12 @@ List packets; ///< The cargo packets in this list - /** - * Update the cache to reflect adding of this packet. - * Increases count and days_in_transit - * @param cp a new packet to be inserted - */ void AddToCache(const CargoPacket *cp); - - /** - * Update the cached values to reflect the removal of this packet. - * Decreases count and days_in_transit - * @param cp Packet to be removed from cache - */ void RemoveFromCache(const CargoPacket *cp); public: /** Create the cargo list */ CargoList() {} - /** And destroy it ("frees" all cargo packets) */ ~CargoList(); /** @@ -277,47 +239,12 @@ } - /** - * Appends the given cargo packet - * @warning After appending this packet may not exist anymore! - * @note Do not use the cargo packet anymore after it has been appended to this CargoList! - * @param cp the cargo packet to add - * @pre cp != NULL - */ void Append(CargoPacket *cp); - - /** - * Truncates the cargo in this list to the given amount. It leaves the - * first count cargo entities and removes the rest. - * @param max_remaining the maximum amount of entities to be in the list after the command - */ void Truncate(uint max_remaining); - /** - * Moves the given amount of cargo to another list. - * Depending on the value of mta the side effects of this function differ: - * - MTA_FINAL_DELIVERY: destroys the packets that do not originate from a specific station - * - MTA_CARGO_LOAD: sets the loaded_at_xy value of the moved packets - * - MTA_TRANSFER: just move without side effects - * - MTA_UNLOAD: just move without side effects - * @param dest the destination to move the cargo to - * @param count the amount of cargo entities to move - * @param mta how to handle the moving (side effects) - * @param data Depending on mta the data of this variable differs: - * - MTA_FINAL_DELIVERY - station ID of packet's origin not to remove - * - MTA_CARGO_LOAD - station's tile index of load - * - MTA_TRANSFER - unused - * - MTA_UNLOAD - unused - * @param payment The payment helper - * - * @pre mta == MTA_FINAL_DELIVERY || dest != NULL - * @pre mta == MTA_UNLOAD || mta == MTA_CARGO_LOAD || payment != NULL - * @return true if there are still packets that might be moved from this cargo list - */ template <class Tother_inst> bool MoveTo(Tother_inst *dest, uint count, MoveToAction mta, CargoPayment *payment, uint data = 0); - /** Invalidates the cached data and rebuild it */ void InvalidateCache(); }; @@ -331,18 +258,7 @@ Money feeder_share; ///< Cache for the feeder share - /** - * Update the cache to reflect adding of this packet. - * Increases count, feeder share and days_in_transit - * @param cp a new packet to be inserted - */ void AddToCache(const CargoPacket *cp); - - /** - * Update the cached values to reflect the removal of this packet. - * Decreases count, feeder share and days_in_transit - * @param cp Packet to be removed from cache - */ void RemoveFromCache(const CargoPacket *cp); public: @@ -360,12 +276,8 @@ return this->feeder_share; } - /** - * Ages the all cargo in this list - */ void AgeCargo(); - /** Invalidates the cached data and rebuild it */ void InvalidateCache(); /**
--- a/src/cheat.cpp +++ b/src/cheat.cpp @@ -19,6 +19,10 @@ memset(&_cheats, 0, sizeof(Cheats)); } +/** + * Return true if any cheat has been used, false otherwise + * @return has a cheat been used? + */ bool CheatHasBeenUsed() { /* Cannot use lengthof because _cheats is of type Cheats, not Cheat */
--- a/src/cheat_func.h +++ b/src/cheat_func.h @@ -18,10 +18,6 @@ void ShowCheatWindow(); -/** - * Return true if any cheat has been used, false otherwise - * @return has a cheat been used? - */ bool CheatHasBeenUsed(); #endif /* CHEAT_FUNC_H */
--- a/src/command_func.h +++ b/src/command_func.h @@ -34,47 +34,24 @@ */ #define return_cmd_error(errcode) return CommandCost(errcode); -/** - * Execute a command - */ CommandCost DoCommand(TileIndex tile, uint32 p1, uint32 p2, DoCommandFlag flags, uint32 cmd, const char *text = NULL); CommandCost DoCommand(const CommandContainer *container, DoCommandFlag flags); -/** - * Execute a network safe DoCommand function - */ bool DoCommandP(TileIndex tile, uint32 p1, uint32 p2, uint32 cmd, CommandCallback *callback = NULL, const char *text = NULL, bool my_cmd = true); bool DoCommandP(const CommandContainer *container, bool my_cmd = true); -/** Internal helper function for DoCommandP. Do not use. */ CommandCost DoCommandPInternal(TileIndex tile, uint32 p1, uint32 p2, uint32 cmd, CommandCallback *callback, const char *text, bool my_cmd, bool estimate_only); #ifdef ENABLE_NETWORK -/** - * Send a command over the network - */ void NetworkSendCommand(TileIndex tile, uint32 p1, uint32 p2, uint32 cmd, CommandCallback *callback, const char *text, CompanyID company); #endif /* ENABLE_NETWORK */ extern Money _additional_cash_required; -/** - * Checks if a integer value belongs to a command. - */ bool IsValidCommand(uint32 cmd); -/** - * Returns the flags from a given command. - */ byte GetCommandFlags(uint32 cmd); -/** - * Returns the name of a given command. - */ const char *GetCommandName(uint32 cmd); -/** - * Returns the current money available which can be used for a command. - */ Money GetAvailableMoneyForCommand(); - bool IsCommandAllowedWhilePaused(uint32 cmd); /**
--- a/src/crashlog.cpp +++ b/src/crashlog.cpp @@ -73,6 +73,12 @@ return buffer; } +/** + * Writes OpenTTD's version to the buffer. + * @param buffer The begin where to write at. + * @param last The last position in the buffer to write to. + * @return the position of the \c '\0' character after the buffer. + */ char *CrashLog::LogOpenTTDVersion(char *buffer, const char *last) const { return buffer + seprintf(buffer, last, @@ -105,6 +111,13 @@ ); } +/** + * Writes the (important) configuration settings to the buffer. + * E.g. graphics set, sound set, blitter and AIs. + * @param buffer The begin where to write at. + * @param last The last position in the buffer to write to. + * @return the position of the \c '\0' character after the buffer. + */ char *CrashLog::LogConfiguration(char *buffer, const char *last) const { buffer += seprintf(buffer, last, @@ -181,6 +194,12 @@ # include <zlib.h> #endif +/** + * Writes information (versions) of the used libraries. + * @param buffer The begin where to write at. + * @param last The last position in the buffer to write to. + * @return the position of the \c '\0' character after the buffer. + */ char *CrashLog::LogLibraries(char *buffer, const char *last) const { buffer += seprintf(buffer, last, "Libraries:\n"); @@ -243,11 +262,21 @@ return buffer; } +/** + * Helper function for printing the gamelog. + * @param s the string to print. + */ /* static */ void CrashLog::GamelogFillCrashLog(const char *s) { CrashLog::gamelog_buffer += seprintf(CrashLog::gamelog_buffer, CrashLog::gamelog_last, "%s\n", s); } +/** + * Writes the gamelog data to the buffer. + * @param buffer The begin where to write at. + * @param last The last position in the buffer to write to. + * @return the position of the \c '\0' character after the buffer. + */ char *CrashLog::LogGamelog(char *buffer, const char *last) const { CrashLog::gamelog_buffer = buffer; @@ -256,6 +285,12 @@ return CrashLog::gamelog_buffer + seprintf(CrashLog::gamelog_buffer, last, "\n"); } +/** + * Fill the crash log buffer with all data of a crash log. + * @param buffer The begin where to write at. + * @param last The last position in the buffer to write to. + * @return the position of the \c '\0' character after the buffer. + */ char *CrashLog::FillCrashLog(char *buffer, const char *last) const { time_t cur_time = time(NULL); @@ -281,6 +316,15 @@ return buffer; } +/** + * Write the crash log to a file. + * @note On success the filename will be filled with the full path of the + * crash log file. Make sure filename is at least \c MAX_PATH big. + * @param buffer The begin of the buffer to write to the disk. + * @param filename Output for the filename of the written file. + * @param filename_last The last position in the filename buffer. + * @return true when the crash log was successfully written. + */ bool CrashLog::WriteCrashLog(const char *buffer, char *filename, const char *filename_last) const { seprintf(filename, filename_last, "%scrash.log", _personal_dir); @@ -301,6 +345,14 @@ return 0; } +/** + * Write the (crash) savegame to a file. + * @note On success the filename will be filled with the full path of the + * crash save file. Make sure filename is at least \c MAX_PATH big. + * @param filename Output for the filename of the written file. + * @param filename_last The last position in the filename buffer. + * @return true when the crash save was successfully made. + */ bool CrashLog::WriteSavegame(char *filename, const char *filename_last) const { /* If the map array doesn't exist, saving will fail too. If the map got @@ -319,6 +371,14 @@ } } +/** + * Write the (crash) screenshot to a file. + * @note On success the filename will be filled with the full path of the + * screenshot. Make sure filename is at least \c MAX_PATH big. + * @param filename Output for the filename of the written file. + * @param filename_last The last position in the filename buffer. + * @return true when the crash screenshot was successfully made. + */ bool CrashLog::WriteScreenshot(char *filename, const char *filename_last) const { /* Don't draw when we have invalid screen size */ @@ -329,6 +389,12 @@ return res; } +/** + * Makes the crash log, writes it to a file and then subsequently tries + * to make a crash dump and crash savegame. It uses DEBUG to write + * information like paths to the console. + * @return true when everything is made successfully. + */ bool CrashLog::MakeCrashLog() const { /* Don't keep looping logging crashes. */ @@ -384,11 +450,19 @@ return ret; } +/** + * Sets a message for the error message handler. + * @param message The error message of the error. + */ /* static */ void CrashLog::SetErrorMessage(const char *message) { CrashLog::message = message; } +/** + * Try to close the sound/video stuff so it doesn't keep lingering around + * incorrect video states or so, e.g. keeping dpmi disabled. + */ /* static */ void CrashLog::AfterCrashLogCleanup() { if (_music_driver != NULL) _music_driver->Stop();
--- a/src/crashlog.h +++ b/src/crashlog.h @@ -26,10 +26,6 @@ /** Temporary 'local' location of the end of the buffer. */ static const char *gamelog_last; - /** - * Helper function for printing the gamelog. - * @param s the string to print. - */ static void GamelogFillCrashLog(const char *s); protected: /** @@ -85,60 +81,16 @@ virtual char *LogModules(char *buffer, const char *last) const; - /** - * Writes OpenTTD's version to the buffer. - * @param buffer The begin where to write at. - * @param last The last position in the buffer to write to. - * @return the position of the \c '\0' character after the buffer. - */ char *LogOpenTTDVersion(char *buffer, const char *last) const; - - /** - * Writes the (important) configuration settings to the buffer. - * E.g. graphics set, sound set, blitter and AIs. - * @param buffer The begin where to write at. - * @param last The last position in the buffer to write to. - * @return the position of the \c '\0' character after the buffer. - */ char *LogConfiguration(char *buffer, const char *last) const; - - /** - * Writes information (versions) of the used libraries. - * @param buffer The begin where to write at. - * @param last The last position in the buffer to write to. - * @return the position of the \c '\0' character after the buffer. - */ char *LogLibraries(char *buffer, const char *last) const; - - /** - * Writes the gamelog data to the buffer. - * @param buffer The begin where to write at. - * @param last The last position in the buffer to write to. - * @return the position of the \c '\0' character after the buffer. - */ char *LogGamelog(char *buffer, const char *last) const; public: /** Stub destructor to silence some compilers. */ virtual ~CrashLog() {} - /** - * Fill the crash log buffer with all data of a crash log. - * @param buffer The begin where to write at. - * @param last The last position in the buffer to write to. - * @return the position of the \c '\0' character after the buffer. - */ char *FillCrashLog(char *buffer, const char *last) const; - - /** - * Write the crash log to a file. - * @note On success the filename will be filled with the full path of the - * crash log file. Make sure filename is at least \c MAX_PATH big. - * @param buffer The begin of the buffer to write to the disk. - * @param filename Output for the filename of the written file. - * @param filename_last The last position in the filename buffer. - * @return true when the crash log was successfully written. - */ bool WriteCrashLog(const char *buffer, char *filename, const char *filename_last) const; /** @@ -151,33 +103,9 @@ * was successful (not all OSes support dumping files). */ virtual int WriteCrashDump(char *filename, const char *filename_last) const; - - /** - * Write the (crash) savegame to a file. - * @note On success the filename will be filled with the full path of the - * crash save file. Make sure filename is at least \c MAX_PATH big. - * @param filename Output for the filename of the written file. - * @param filename_last The last position in the filename buffer. - * @return true when the crash save was successfully made. - */ bool WriteSavegame(char *filename, const char *filename_last) const; - - /** - * Write the (crash) screenshot to a file. - * @note On success the filename will be filled with the full path of the - * screenshot. Make sure filename is at least \c MAX_PATH big. - * @param filename Output for the filename of the written file. - * @param filename_last The last position in the filename buffer. - * @return true when the crash screenshot was successfully made. - */ bool WriteScreenshot(char *filename, const char *filename_last) const; - /** - * Makes the crash log, writes it to a file and then subsequently tries - * to make a crash dump and crash savegame. It uses DEBUG to write - * information like paths to the console. - * @return true when everything is made successfully. - */ bool MakeCrashLog() const; /** @@ -187,16 +115,7 @@ */ static void InitialiseCrashLog(); - /** - * Sets a message for the error message handler. - * @param message The error message of the error. - */ static void SetErrorMessage(const char *message); - - /** - * Try to close the sound/video stuff so it doesn't keep lingering around - * incorrect video states or so, e.g. keeping dpmi disabled. - */ static void AfterCrashLogCleanup(); };