From d946841eff2e0a24acf2683f65c4ef11ff5c3619 Mon Sep 17 00:00:00 2001 From: rubidium Date: Mon, 2 May 2011 20:59:54 +0000 Subject: [PATCH] (svn r22413) -Document: even more stuff --- src/airport.cpp | 15 ++++++++++++++- src/articulated_vehicles.cpp | 15 +++++++++++++++ src/autoreplace.cpp | 1 + src/autoreplace_gui.cpp | 5 +++++ src/base_media_func.h | 6 ++++++ src/bridge.h | 5 +++++ src/cargo_type.h | 2 +- src/cargopacket.cpp | 2 +- src/cheat.cpp | 2 ++ src/clear_map.h | 1 + src/company_cmd.cpp | 3 +++ src/company_gui.cpp | 9 ++++++++- src/company_manager_face.h | 1 + src/economy.cpp | 6 +++++- src/tunnelbridge_cmd.cpp | 11 ++++++++++- 15 files changed, 78 insertions(+), 6 deletions(-) diff --git a/src/airport.cpp b/src/airport.cpp index 2173da9ed6..389cbe2b8d 100644 --- a/src/airport.cpp +++ b/src/airport.cpp @@ -16,6 +16,14 @@ #include "table/airporttile_ids.h" +/** + * Define a generic airport. + * @param name Suffix of the names of the airport data. + * @param terminals The terminals. + * @param num_helipads Number of heli pads. + * @param flags Information about the class of FTA. + * @param delta_z Height of the arport above the land. + */ #define AIRPORT_GENERIC(name, terminals, num_helipads, flags, delta_z) \ static AirportFTAClass _airportfta_ ## name(_airport_moving_data_ ## name, terminals, \ num_helipads, _airport_entries_ ## name, flags, _airport_fta_ ## name, delta_z); @@ -154,7 +162,12 @@ static uint16 AirportGetNofElements(const AirportFTAbuildup *apFA) return nofelements; } - +/** + * Construct the FTA given a description. + * @param nofelements The number of elements in the FTA. + * @param apFA The description of the FTA. + * @return The FTA describing the airport. + */ static AirportFTA *AirportBuildAutomata(uint nofelements, const AirportFTAbuildup *apFA) { AirportFTA *FAutomata = MallocT(nofelements); diff --git a/src/articulated_vehicles.cpp b/src/articulated_vehicles.cpp index 0ef4d9bc47..2350dcb920 100644 --- a/src/articulated_vehicles.cpp +++ b/src/articulated_vehicles.cpp @@ -40,6 +40,12 @@ static EngineID GetNextArticulatedPart(uint index, EngineID front_type, Vehicle return GetNewEngineID(GetEngineGRF(front_type), Engine::Get(front_type)->type, GB(callback, 0, 7)); } +/** + * Count the number of articulated parts of an engine. + * @param engine_type The engine to get the number of parts of. + * @param purchase_window Whether we are in the scope of the purchase window or not, i.e. whether we cannot allocate vehicles. + * @return The nmumber of parts. + */ uint CountArticulatedParts(EngineID engine_type, bool purchase_window) { if (!HasBit(EngInfo(engine_type)->callback_mask, CBM_VEHICLE_ARTIC_ENGINE)) return 0; @@ -101,6 +107,11 @@ static inline uint32 GetAvailableVehicleCargoTypes(EngineID engine, bool include return cargos; } +/** + * Get the capacity of the parts of a given engine. + * @param engine The engine to get the capacities from. + * @return The cargo capacities. + */ CargoArray GetCapacityOfArticulatedParts(EngineID engine) { CargoArray capacity; @@ -276,6 +287,10 @@ void CheckConsistencyOfArticulatedVehicle(const Vehicle *v) } } +/** + * Add the remaining articulated parts to the given vehicle. + * @param first The head of the articulated bit. + */ void AddArticulatedParts(Vehicle *first) { VehicleType type = first->type; diff --git a/src/autoreplace.cpp b/src/autoreplace.cpp index 4a7dfcd01f..aed2c0e829 100644 --- a/src/autoreplace.cpp +++ b/src/autoreplace.cpp @@ -15,6 +15,7 @@ #include "autoreplace_base.h" #include "core/pool_func.hpp" +/** The pool of autoreplace "orders". */ EngineRenewPool _enginerenew_pool("EngineRenew"); INSTANTIATE_POOL_METHODS(EngineRenew) diff --git a/src/autoreplace_gui.cpp b/src/autoreplace_gui.cpp index 86a84fec76..e95606494c 100644 --- a/src/autoreplace_gui.cpp +++ b/src/autoreplace_gui.cpp @@ -579,6 +579,11 @@ static const WindowDesc _replace_vehicle_desc( _nested_replace_vehicle_widgets, lengthof(_nested_replace_vehicle_widgets) ); +/** + * Show the autoreplace configuration window for a particular group. + * @param id_g The group to replace the vehicles for. + * @param vehicletype The type of vehicles in the group. + */ void ShowReplaceGroupVehicleWindow(GroupID id_g, VehicleType vehicletype) { DeleteWindowById(WC_REPLACE_VEHICLE, vehicletype); diff --git a/src/base_media_func.h b/src/base_media_func.h index 69eaccf5fe..6adf397c4a 100644 --- a/src/base_media_func.h +++ b/src/base_media_func.h @@ -274,6 +274,12 @@ template #if defined(ENABLE_NETWORK) #include "network/network_content.h" +/** + * Check whether there's a base set matching some information. + * @param ci The content info to compare it to. + * @param md5sum Should the MD5 checksum be tested as well? + * @param s The list with sets. + */ template bool HasBaseSet(const ContentInfo *ci, bool md5sum, const Tbase_set *s) { for (; s != NULL; s = s->next) { diff --git a/src/bridge.h b/src/bridge.h index 521c3f1280..badf045e39 100644 --- a/src/bridge.h +++ b/src/bridge.h @@ -59,6 +59,11 @@ extern BridgeSpec _bridge[MAX_BRIDGES]; Foundation GetBridgeFoundation(Slope tileh, Axis axis); bool HasBridgeFlatRamp(Slope tileh, Axis axis); +/** + * Get the specification of a bridge type. + * @param i The type of bridge to get the specification for. + * @return The specification. + */ static inline const BridgeSpec *GetBridgeSpec(BridgeType i) { assert(i < lengthof(_bridge)); diff --git a/src/cargo_type.h b/src/cargo_type.h index d2261c0377..2ca29d203c 100644 --- a/src/cargo_type.h +++ b/src/cargo_type.h @@ -113,7 +113,7 @@ enum SourceType { ST_TOWN, ///< Source/destination is a town ST_HEADQUARTERS, ///< Source/destination are company headquarters }; -typedef SimpleTinyEnumT SourceTypeByte; +typedef SimpleTinyEnumT SourceTypeByte; ///< The SourceType packed into a byte for savegame purposes. typedef uint16 SourceID; ///< Contains either industry ID, town ID or company ID (or INVALID_SOURCE) static const SourceID INVALID_SOURCE = 0xFFFF; ///< Invalid/unknown index of source diff --git a/src/cargopacket.cpp b/src/cargopacket.cpp index 55c62cd02e..2c93d8c85f 100644 --- a/src/cargopacket.cpp +++ b/src/cargopacket.cpp @@ -246,7 +246,7 @@ void CargoList::Truncate(uint max_remaining) * - MTA_TRANSFER: Just move without side effects. * - MTA_UNLOAD: Just move without side effects. * @param dest Destination to move the cargo to. - * @param count Amount of cargo entities to move. + * @param max_move 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. diff --git a/src/cheat.cpp b/src/cheat.cpp index a0df149825..f8dae235fa 100644 --- a/src/cheat.cpp +++ b/src/cheat.cpp @@ -12,8 +12,10 @@ #include "stdafx.h" #include "cheat_type.h" +/** All the cheats. */ Cheats _cheats; +/** Reinitialise all the cheats. */ void InitializeCheats() { memset(&_cheats, 0, sizeof(Cheats)); diff --git a/src/clear_map.h b/src/clear_map.h index ed5409a941..8a346fd4e2 100644 --- a/src/clear_map.h +++ b/src/clear_map.h @@ -310,6 +310,7 @@ static inline void MakeField(TileIndex t, uint field_type, IndustryID industry) /** * Make a snow tile. * @param t the tile to make snowy + * @param density The density of snowiness. * @pre GetClearGround(t) != CLEAR_SNOW */ static inline void MakeSnow(TileIndex t, uint density = 0) diff --git a/src/company_cmd.cpp b/src/company_cmd.cpp index 4944b66b1b..46c310e826 100644 --- a/src/company_cmd.cpp +++ b/src/company_cmd.cpp @@ -393,7 +393,9 @@ bad_town_name:; } } +/** Sorting weights for the company colours. */ static const byte _colour_sort[COLOUR_END] = {2, 2, 3, 2, 3, 2, 3, 2, 3, 2, 2, 2, 3, 1, 1, 1}; +/** Similar colours, so we can try to prevent same coloured companies. */ static const Colours _similar_colour[COLOUR_END][2] = { { COLOUR_BLUE, COLOUR_LIGHT_BLUE }, // COLOUR_DARK_BLUE { COLOUR_GREEN, COLOUR_DARK_GREEN }, // COLOUR_PALE_GREEN @@ -685,6 +687,7 @@ static void HandleBankruptcyTakeover(Company *c) } } +/** Called every tick for updating some company info. */ void OnTick_Companies() { if (_game_mode == GM_EDITOR) return; diff --git a/src/company_gui.cpp b/src/company_gui.cpp index 968a216d0d..84040f0803 100644 --- a/src/company_gui.cpp +++ b/src/company_gui.cpp @@ -2068,6 +2068,10 @@ static const WindowDesc _company_desc( _nested_company_widgets, lengthof(_nested_company_widgets) ); +/** + * Show the window with the overview of the company. + * @param company The company to show the window for. + */ void ShowCompany(CompanyID company) { if (!Company::IsValidID(company)) return; @@ -2175,7 +2179,10 @@ static const WindowDesc _buy_company_desc( _nested_buy_company_widgets, lengthof(_nested_buy_company_widgets) ); - +/** + * Show the query to buy another company. + * @param company The company to buy. + */ void ShowBuyCompanyDialog(CompanyID company) { AllocateWindowDescFront(&_buy_company_desc, company); diff --git a/src/company_manager_face.h b/src/company_manager_face.h index 80614a16f4..43aabeecc9 100644 --- a/src/company_manager_face.h +++ b/src/company_manager_face.h @@ -84,6 +84,7 @@ static const CompanyManagerFaceBitsInfo _cmf_info[] = { /* CMFV_TIE_EARRING */ { 28, 3, { 6, 3, 6, 3 }, { 0x372, 0x37F, 0x372, 0x3D1 } }, ///< Depends on CMFV_HAS_TIE_EARRING /* CMFV_GLASSES */ { 31, 1, { 2, 2, 2, 2 }, { 0x347, 0x347, 0x3AE, 0x3AE } } ///< Depends on CMFV_HAS_GLASSES }; +/** Make sure the table's size is right. */ assert_compile(lengthof(_cmf_info) == CMFV_END); /** diff --git a/src/economy.cpp b/src/economy.cpp index 584eea7c7f..6f2604c27d 100644 --- a/src/economy.cpp +++ b/src/economy.cpp @@ -281,7 +281,11 @@ int UpdateCompanyRatingAndValue(Company *c, bool update) return score; } -/* use INVALID_OWNER as new_owner to delete the company. */ +/** + * Change the ownership of all the items of a company. + * @param old_owner The company that gets removed. + * @param new_owner The company to merge to, or INVALID_OWNER to remove the company. + */ void ChangeOwnershipOfCompanyItems(Owner old_owner, Owner new_owner) { /* We need to set _current_company to old_owner before we try to move diff --git a/src/tunnelbridge_cmd.cpp b/src/tunnelbridge_cmd.cpp index 54a7c93707..51323f0c15 100644 --- a/src/tunnelbridge_cmd.cpp +++ b/src/tunnelbridge_cmd.cpp @@ -89,6 +89,12 @@ int CalcBridgeLenCostFactor(int length) } } +/** + * Get the foundation for a bridge. + * @param tileh The slope to build the bridge on. + * @param axis The axis of the bridge entrace. + * @return The foundatiton required. + */ Foundation GetBridgeFoundation(Slope tileh, Axis axis) { if (tileh == SLOPE_FLAT || @@ -1208,7 +1214,10 @@ static BridgePieces CalcBridgePiece(uint north, uint south) } } - +/** + * Draw the middle bits of a bridge. + * @param ti Tile information of the tile to draw it on. + */ void DrawBridgeMiddle(const TileInfo *ti) { /* Sectional view of bridge bounding boxes: