From 4d5dbf51707c42c24eeafdb65016b079c54adcf2 Mon Sep 17 00:00:00 2001 From: rubidium Date: Mon, 2 May 2011 16:14:23 +0000 Subject: [PATCH] (svn r22410) -Document: some more bits ;) --- src/debug.h | 7 ++++++- src/music.cpp | 3 ++- src/music/allegro_m.h | 2 ++ src/music/bemidi.cpp | 2 ++ src/music/bemidi.h | 2 ++ src/music/dmusic.h | 2 ++ src/music/extmidi.cpp | 2 ++ src/music/libtimidity.cpp | 4 +++- src/music/libtimidity.h | 2 ++ src/music/music_driver.hpp | 21 +++++++++++++++++++ src/music/null_m.cpp | 2 +- src/music/null_m.h | 2 ++ src/music/os2_m.cpp | 6 ++++++ src/music/os2_m.h | 2 ++ src/music/win32_m.h | 2 ++ src/network/network_command.cpp | 1 + src/network/network_gamelist.cpp | 3 ++- src/network/network_type.h | 7 +++++-- src/newgrf_airport.cpp | 7 +++++++ src/newgrf_airport.h | 6 +++--- src/newgrf_class_func.h | 4 ++++ src/newgrf_commons.cpp | 9 ++++++++- src/newgrf_config.cpp | 4 ++-- src/newgrf_config.h | 2 +- src/newgrf_debug_gui.cpp | 1 + src/newgrf_generic.cpp | 6 +++--- src/newgrf_generic.h | 24 +++++++++++++--------- src/newgrf_industries.cpp | 16 +++++++++++++++ src/newgrf_railtype.cpp | 14 +++++++++++++ src/news_gui.cpp | 3 +++ src/news_type.h | 10 ++++++++- src/order_backup.cpp | 2 +- src/order_backup.h | 10 +++++++++ src/pathfinder/pf_performance_timer.hpp | 2 +- src/pathfinder/yapf/nodelist.hpp | 3 +++ src/pathfinder/yapf/yapf.h | 2 +- src/pathfinder/yapf/yapf_costbase.hpp | 12 ++++++----- src/pathfinder/yapf/yapf_costrail.hpp | 1 - src/pbs.h | 10 +++++++++ src/sound/allegro_s.h | 2 ++ src/sound/null_s.h | 2 ++ src/sound/sdl_s.h | 2 ++ src/sound/sound_driver.hpp | 8 +++++++- src/sound/win32_s.h | 2 ++ src/video/allegro_v.h | 2 ++ src/video/dedicated_v.h | 2 ++ src/video/null_v.h | 4 +++- src/video/sdl_v.h | 2 ++ src/video/video_driver.hpp | 27 +++++++++++++++++++++++++ src/video/win32_v.cpp | 5 +++++ src/video/win32_v.h | 2 ++ 51 files changed, 241 insertions(+), 39 deletions(-) diff --git a/src/debug.h b/src/debug.h index 213872474b..76b66f3418 100644 --- a/src/debug.h +++ b/src/debug.h @@ -61,6 +61,12 @@ const char *GetDebugString(); /* Shorter form for passing filename and linenumber */ #define FILE_LINE __FILE__, __LINE__ +/** + * Get the tick counter from the CPU (high precision timing). + * @return The count. + */ +uint64 ottd_rdtsc(); + /* Used for profiling * * Usage: @@ -83,7 +89,6 @@ const char *GetDebugString(); * it with another block. **/ #define TIC() {\ - extern uint64 ottd_rdtsc();\ uint64 _xxx_ = ottd_rdtsc();\ static uint64 __sum__ = 0;\ static uint32 __i__ = 0; diff --git a/src/music.cpp b/src/music.cpp index a6c8ea78f7..de642cc30b 100644 --- a/src/music.cpp +++ b/src/music.cpp @@ -11,7 +11,7 @@ #include "stdafx.h" -/* The type of set we're replacing */ +/** The type of set we're replacing */ #define SET_TYPE "music" #include "base_media_func.h" @@ -24,6 +24,7 @@ static const char * const _music_file_names[] = { "new_0", "new_1", "new_2", "new_3", "new_4", "new_5", "new_6", "new_7", "new_8", "new_9", "ezy_0", "ezy_1", "ezy_2", "ezy_3", "ezy_4", "ezy_5", "ezy_6", "ezy_7", "ezy_8", "ezy_9", }; +/** Make sure we aren't messing things up. */ assert_compile(lengthof(_music_file_names) == NUM_SONGS_AVAILABLE); template diff --git a/src/music/allegro_m.h b/src/music/allegro_m.h index 1d61b30f82..2160c396e5 100644 --- a/src/music/allegro_m.h +++ b/src/music/allegro_m.h @@ -14,6 +14,7 @@ #include "music_driver.hpp" +/** Allegro's music player. */ class MusicDriver_Allegro: public MusicDriver { public: /* virtual */ const char *Start(const char * const *param); @@ -30,6 +31,7 @@ public: /* virtual */ const char *GetName() const { return "allegro"; } }; +/** Factory for allegro's music player. */ class FMusicDriver_Allegro: public MusicDriverFactory { public: #if !defined(WITH_SDL) && defined(WITH_ALLEGRO) diff --git a/src/music/bemidi.cpp b/src/music/bemidi.cpp index 070e558196..5ee62dfe51 100644 --- a/src/music/bemidi.cpp +++ b/src/music/bemidi.cpp @@ -16,8 +16,10 @@ /* BeOS System Includes */ #include +/** The file we're playing. */ static BMidiSynthFile midiSynthFile; +/** Factory for BeOS' midi player. */ static FMusicDriver_BeMidi iFMusicDriver_BeMidi; const char *MusicDriver_BeMidi::Start(const char * const *parm) diff --git a/src/music/bemidi.h b/src/music/bemidi.h index 07b275f956..1b280e667d 100644 --- a/src/music/bemidi.h +++ b/src/music/bemidi.h @@ -14,6 +14,7 @@ #include "music_driver.hpp" +/** The midi player for BeOS. */ class MusicDriver_BeMidi: public MusicDriver { public: /* virtual */ const char *Start(const char * const *param); @@ -30,6 +31,7 @@ public: /* virtual */ const char *GetName() const { return "bemidi"; } }; +/** Factory for the BeOS midi player. */ class FMusicDriver_BeMidi: public MusicDriverFactory { public: static const int priority = 10; diff --git a/src/music/dmusic.h b/src/music/dmusic.h index 74368de23e..b3fc996106 100644 --- a/src/music/dmusic.h +++ b/src/music/dmusic.h @@ -14,6 +14,7 @@ #include "music_driver.hpp" +/** Music player making use of DirectX. */ class MusicDriver_DMusic: public MusicDriver { public: /* virtual */ const char *Start(const char * const *param); @@ -30,6 +31,7 @@ public: /* virtual */ const char *GetName() const { return "dmusic"; } }; +/** Factory for the DirectX music player. */ class FMusicDriver_DMusic: public MusicDriverFactory { public: static const int priority = 10; diff --git a/src/music/extmidi.cpp b/src/music/extmidi.cpp index 6c8ee8d690..93492aa996 100644 --- a/src/music/extmidi.cpp +++ b/src/music/extmidi.cpp @@ -26,9 +26,11 @@ #include #ifndef EXTERNAL_PLAYER +/** The default external midi player. */ #define EXTERNAL_PLAYER "timidity" #endif +/** Factory for the midi player that uses external players. */ static FMusicDriver_ExtMidi iFMusicDriver_ExtMidi; const char *MusicDriver_ExtMidi::Start(const char * const * parm) diff --git a/src/music/libtimidity.cpp b/src/music/libtimidity.cpp index 82f011c237..92f17212c3 100644 --- a/src/music/libtimidity.cpp +++ b/src/music/libtimidity.cpp @@ -26,6 +26,7 @@ #include #endif /* PSP */ +/** The state of playing. */ enum MidiState { MIDI_STOPPED = 0, MIDI_PLAYING = 1, @@ -39,7 +40,7 @@ static struct { MidiState status; uint32 song_length; uint32 song_position; -} _midi; +} _midi; ///< Metadata about the midi we're playing. #if defined(PSP) static void AudioOutCallback(void *buf, unsigned int _reqn, void *userdata) @@ -51,6 +52,7 @@ static void AudioOutCallback(void *buf, unsigned int _reqn, void *userdata) } #endif /* PSP */ +/** Factory for the libtimidity driver. */ static FMusicDriver_LibTimidity iFMusicDriver_LibTimidity; const char *MusicDriver_LibTimidity::Start(const char * const *param) diff --git a/src/music/libtimidity.h b/src/music/libtimidity.h index 7839462dd1..4f93436192 100644 --- a/src/music/libtimidity.h +++ b/src/music/libtimidity.h @@ -14,6 +14,7 @@ #include "music_driver.hpp" +/** Music driver making use of libtimidity. */ class MusicDriver_LibTimidity: public MusicDriver { public: /* virtual */ const char *Start(const char * const *param); @@ -30,6 +31,7 @@ public: /* virtual */ const char *GetName() const { return "libtimidity"; } }; +/** Factory for the libtimidity driver. */ class FMusicDriver_LibTimidity: public MusicDriverFactory { public: static const int priority = 5; diff --git a/src/music/music_driver.hpp b/src/music/music_driver.hpp index c3f565866d..70a1e37a5a 100644 --- a/src/music/music_driver.hpp +++ b/src/music/music_driver.hpp @@ -14,20 +14,41 @@ #include "../driver.h" +/** Driver for all music playback. */ class MusicDriver: public Driver { public: + /** + * Play a particular song. + * @param filename The name of file with the song to play. + */ virtual void PlaySong(const char *filename) = 0; + /** + * Stop playing the current song. + */ virtual void StopSong() = 0; + /** + * Are we currently playing a song? + * @return True if a song is being played. + */ virtual bool IsSongPlaying() = 0; + /** + * Set the volume, if possible. + * @param vol The new volume. + */ virtual void SetVolume(byte vol) = 0; }; +/** Base of the factory for the music drivers. */ class MusicDriverFactoryBase: public DriverFactoryBase { }; +/** + * Factory for the music drivers. + * @tparam T The type of the music factory to register. + */ template class MusicDriverFactory: public MusicDriverFactoryBase { public: diff --git a/src/music/null_m.cpp b/src/music/null_m.cpp index fa46d5efb0..cb42a906a5 100644 --- a/src/music/null_m.cpp +++ b/src/music/null_m.cpp @@ -12,5 +12,5 @@ #include "../stdafx.h" #include "null_m.h" +/** The factory for the music player that does nothing. */ static FMusicDriver_Null iFMusicDriver_Null; - diff --git a/src/music/null_m.h b/src/music/null_m.h index 16137356ca..babfd37755 100644 --- a/src/music/null_m.h +++ b/src/music/null_m.h @@ -14,6 +14,7 @@ #include "music_driver.hpp" +/** The music player that does nothing. */ class MusicDriver_Null: public MusicDriver { public: /* virtual */ const char *Start(const char * const *param) { return NULL; } @@ -30,6 +31,7 @@ public: /* virtual */ const char *GetName() const { return "null"; } }; +/** Factory for the null music player. */ class FMusicDriver_Null: public MusicDriverFactory { public: static const int priority = 1; diff --git a/src/music/os2_m.cpp b/src/music/os2_m.cpp index d9fb06138d..ec1fca2645 100644 --- a/src/music/os2_m.cpp +++ b/src/music/os2_m.cpp @@ -29,6 +29,11 @@ * eh? Anyone would think they both came from the same place originally! ;) */ +/** + * Send a midi command. + * @param cmd The command to send. + * @return The result of sending it. + */ static long CDECL MidiSendCommand(const char *cmd, ...) { va_list va; @@ -39,6 +44,7 @@ static long CDECL MidiSendCommand(const char *cmd, ...) return mciSendString(buf, NULL, 0, NULL, 0); } +/** OS/2's music player's factory. */ static FMusicDriver_OS2 iFMusicDriver_OS2; void MusicDriver_OS2::PlaySong(const char *filename) diff --git a/src/music/os2_m.h b/src/music/os2_m.h index 87c45873ce..054526e59e 100644 --- a/src/music/os2_m.h +++ b/src/music/os2_m.h @@ -14,6 +14,7 @@ #include "music_driver.hpp" +/** OS/2's music player. */ class MusicDriver_OS2: public MusicDriver { public: /* virtual */ const char *Start(const char * const *param); @@ -30,6 +31,7 @@ public: /* virtual */ const char *GetName() const { return "os2"; } }; +/** Factory for OS/2's music player. */ class FMusicDriver_OS2: public MusicDriverFactory { public: static const int priority = 10; diff --git a/src/music/win32_m.h b/src/music/win32_m.h index d596d3a9fc..cf46fbc152 100644 --- a/src/music/win32_m.h +++ b/src/music/win32_m.h @@ -14,6 +14,7 @@ #include "music_driver.hpp" +/** The Windows music player. */ class MusicDriver_Win32: public MusicDriver { public: /* virtual */ const char *Start(const char * const *param); @@ -30,6 +31,7 @@ public: /* virtual */ const char *GetName() const { return "win32"; } }; +/** Factory for Windows' music player. */ class FMusicDriver_Win32: public MusicDriverFactory { public: static const int priority = 5; diff --git a/src/network/network_command.cpp b/src/network/network_command.cpp index d68021205a..27e8338fb9 100644 --- a/src/network/network_command.cpp +++ b/src/network/network_command.cpp @@ -275,6 +275,7 @@ static void DistributeQueue(CommandQueue *queue, const NetworkClientSocket *owne } } +/** Distribute the commands of ourself and the clients. */ void NetworkDistributeCommands() { /* First send the server's commands. */ diff --git a/src/network/network_gamelist.cpp b/src/network/network_gamelist.cpp index 707c5c36b5..4511397dac 100644 --- a/src/network/network_gamelist.cpp +++ b/src/network/network_gamelist.cpp @@ -25,7 +25,9 @@ NetworkGameList *_network_game_list = NULL; +/** Mutex for handling delayed insertion/querying of servers. */ static ThreadMutex *_network_game_list_mutex = ThreadMutex::New(); +/** The games to insert when the GUI thread has time for us. */ static NetworkGameList *_network_game_delayed_insertion_list = NULL; /** @@ -72,7 +74,6 @@ static void NetworkGameListHandleDelayedInsert() * Add a new item to the linked gamelist. If the IP and Port match * return the existing item instead of adding it again * @param address the address of the to-be added item - * @param port the port the server is running on * @return a point to the newly added or already existing item */ NetworkGameList *NetworkGameListAddItem(NetworkAddress address) diff --git a/src/network/network_type.h b/src/network/network_type.h index f40a1cdd5f..ff29492b70 100644 --- a/src/network/network_type.h +++ b/src/network/network_type.h @@ -72,11 +72,13 @@ struct NetworkCompanyState { struct NetworkClientInfo; +/** The type of password we're asking for. */ enum NetworkPasswordType { - NETWORK_GAME_PASSWORD, - NETWORK_COMPANY_PASSWORD, + NETWORK_GAME_PASSWORD, ///< The password of the game. + NETWORK_COMPANY_PASSWORD, ///< The password of the company. }; +/** Destination of our chat messages. */ enum DestType { DESTTYPE_BROADCAST, ///< Send message/notice to all clients (All) DESTTYPE_TEAM, ///< Send message/notice to everyone playing the same company (Team) @@ -98,6 +100,7 @@ enum NetworkAction { NETWORK_ACTION_COMPANY_NEW, }; +/** The error codes we send around in the protocols. */ enum NetworkErrorCode { NETWORK_ERROR_GENERAL, // Try to use this one like never diff --git a/src/newgrf_airport.cpp b/src/newgrf_airport.cpp index ad02efd8d8..395b0e3ad2 100644 --- a/src/newgrf_airport.cpp +++ b/src/newgrf_airport.cpp @@ -238,6 +238,13 @@ uint16 GetAirportCallback(CallbackID callback, uint32 param1, uint32 param2, Sta return group->GetCallbackResult(); } +/** + * Get a custom text for the airport. + * @param as The airport type's specification. + * @param layout The layout index. + * @param callback The callback to call. + * @return The custom text. + */ StringID GetAirportTextCallback(const AirportSpec *as, byte layout, uint16 callback) { const SpriteGroup *group; diff --git a/src/newgrf_airport.h b/src/newgrf_airport.h index d08dfd4ec0..c0aac93961 100644 --- a/src/newgrf_airport.h +++ b/src/newgrf_airport.h @@ -19,7 +19,7 @@ #include "newgrf_commons.h" #include "gfx_type.h" -/* Copy from station_map.h */ +/** Copy from station_map.h */ typedef byte StationGfx; /** Tile-offset / AirportTileID pair. */ @@ -93,10 +93,10 @@ struct AirportSpec { return (byte)(this - specs); } - static AirportSpec dummy; + static AirportSpec dummy; ///< The dummy airport. private: - static AirportSpec specs[NUM_AIRPORTS]; + static AirportSpec specs[NUM_AIRPORTS]; ///< Specs of the airports. }; /** Information related to airport classes. */ diff --git a/src/newgrf_class_func.h b/src/newgrf_class_func.h index 5735889ec8..c4e9f79638 100644 --- a/src/newgrf_class_func.h +++ b/src/newgrf_class_func.h @@ -13,6 +13,10 @@ #include "table/strings.h" +/** + * Helper for defining the class method's signatures. + * @param type The type of the class. + */ #define DEFINE_NEWGRF_CLASS_METHOD(type) \ template \ type NewGRFClass diff --git a/src/newgrf_commons.cpp b/src/newgrf_commons.cpp index cb13af4a65..edb3212bfe 100644 --- a/src/newgrf_commons.cpp +++ b/src/newgrf_commons.cpp @@ -323,7 +323,7 @@ void ObjectOverrideManager::SetEntitySpec(ObjectSpec *spec) * Function used by houses (and soon industries) to get information * on type of "terrain" the tile it is queries sits on. * @param tile TileIndex of the tile been queried - * @param upper_halftile If true, query upper halftile in case of rail tiles. + * @param context The context of the tile. * @return value corresponding to the grf expected format: * Terrain type: 0 normal, 1 desert, 2 rainforest, 4 on or above snowline */ @@ -394,6 +394,13 @@ uint32 GetTerrainType(TileIndex tile, TileContext context) } } +/** + * Get the tile at the given offset. + * @param parameter The NewGRF "encoded" offset. + * @param tile The tile to base the offset from. + * @param signed_offsets Whether the offsets are to be interpreted as signed or not. + * @return The tile at the offset. + */ TileIndex GetNearbyTile(byte parameter, TileIndex tile, bool signed_offsets) { int8 x = GB(parameter, 0, 4); diff --git a/src/newgrf_config.cpp b/src/newgrf_config.cpp index f6e6868034..990cdde753 100644 --- a/src/newgrf_config.cpp +++ b/src/newgrf_config.cpp @@ -667,8 +667,8 @@ const GRFConfig *FindGRFConfig(uint32 grfid, FindGRFConfigMode mode, const uint8 /** Structure for UnknownGRFs; this is a lightweight variant of GRFConfig */ struct UnknownGRF : public GRFIdentifier { - UnknownGRF *next; - GRFTextWrapper *name; + UnknownGRF *next; ///< The next unknown GRF. + GRFTextWrapper *name; ///< Name of the GRF. }; /** diff --git a/src/newgrf_config.h b/src/newgrf_config.h index ad406a9e1e..f06614848e 100644 --- a/src/newgrf_config.h +++ b/src/newgrf_config.h @@ -205,7 +205,7 @@ char *GRFBuildParamList(char *dst, const GRFConfig *c, const char *last); void ShowNewGRFSettings(bool editable, bool show_params, bool exec_changes, GRFConfig **config); #ifdef ENABLE_NETWORK -/* For communication about GRFs over the network */ +/** For communication about GRFs over the network */ #define UNKNOWN_GRF_NAME_PLACEHOLDER "" GRFTextWrapper *FindUnknownGRFName(uint32 grfid, uint8 *md5sum, bool create); #endif /* ENABLE_NETWORK */ diff --git a/src/newgrf_debug_gui.cpp b/src/newgrf_debug_gui.cpp index 6156443671..eb9d16f066 100644 --- a/src/newgrf_debug_gui.cpp +++ b/src/newgrf_debug_gui.cpp @@ -35,6 +35,7 @@ #include "table/strings.h" +/** The sprite picker. */ NewGrfDebugSpritePicker _newgrf_debug_sprite_picker = { SPM_NONE, NULL, 0, SmallVector() }; /** diff --git a/src/newgrf_generic.cpp b/src/newgrf_generic.cpp index 7d83d73b1b..48cab03423 100644 --- a/src/newgrf_generic.cpp +++ b/src/newgrf_generic.cpp @@ -46,9 +46,9 @@ void ResetGenericCallbacks() /** * Add a generic feature callback sprite group to the appropriate feature list. - * @param feature - * @param file - * @param group + * @param feature The feature for the callback. + * @param file The GRF of the callback. + * @param group The sprite group of the callback. */ void AddGenericCallback(uint8 feature, const GRFFile *file, const SpriteGroup *group) { diff --git a/src/newgrf_generic.h b/src/newgrf_generic.h index f079efac85..ffcaf89213 100644 --- a/src/newgrf_generic.h +++ b/src/newgrf_generic.h @@ -14,17 +14,21 @@ #include "cargo_type.h" #include "industry_type.h" +#include "newgrf.h" +struct SpriteGroup; + +/** AI events for asking the NewGRF for information. */ enum AIConstructionEvent { AICE_TRAIN_CHECK_RAIL_ENGINE = 0x00, ///< Check if we should build an engine - AICE_TRAIN_CHECK_ELRAIL_ENGINE = 0x01, - AICE_TRAIN_CHECK_MONORAIL_ENGINE = 0x02, - AICE_TRAIN_CHECK_MAGLEV_ENGINE = 0x03, - AICE_TRAIN_GET_RAIL_WAGON = 0x08, - AICE_TRAIN_GET_ELRAIL_WAGON = 0x09, - AICE_TRAIN_GET_MONORAIL_WAGON = 0x0A, - AICE_TRAIN_GET_MAGLEV_WAGON = 0x0B, - AICE_TRAIN_GET_RAILTYPE = 0x0F, + AICE_TRAIN_CHECK_ELRAIL_ENGINE = 0x01, ///< Check if we should build an engine + AICE_TRAIN_CHECK_MONORAIL_ENGINE = 0x02, ///< Check if we should build an engine + AICE_TRAIN_CHECK_MAGLEV_ENGINE = 0x03, ///< Check if we should build an engine + AICE_TRAIN_GET_RAIL_WAGON = 0x08, ///< Check if we should build an engine + AICE_TRAIN_GET_ELRAIL_WAGON = 0x09, ///< Check if we should build an engine + AICE_TRAIN_GET_MONORAIL_WAGON = 0x0A, ///< Check if we should build an engine + AICE_TRAIN_GET_MAGLEV_WAGON = 0x0B, ///< Check if we should build an engine + AICE_TRAIN_GET_RAILTYPE = 0x0F, ///< Check if we should build a railtype AICE_ROAD_CHECK_ENGINE = 0x00, ///< Check if we should build an engine AICE_ROAD_GET_FIRST_ENGINE = 0x01, ///< Unused, we check all @@ -43,8 +47,8 @@ static const IndustryType IT_AI_UNKNOWN = 0xFE; ///< The AI has no specific indu static const IndustryType IT_AI_TOWN = 0xFF; ///< The AI actually wants to transport to/from a town, not an industry. void ResetGenericCallbacks(); -void AddGenericCallback(uint8 feature, const struct GRFFile *file, const struct SpriteGroup *group); +void AddGenericCallback(uint8 feature, const GRFFile *file, const SpriteGroup *group); -uint16 GetAiPurchaseCallbackResult(uint8 feature, CargoID cargo_type, uint8 default_selection, IndustryType src_industry, IndustryType dst_industry, uint8 distance, AIConstructionEvent event, uint8 count, uint8 station_size, const struct GRFFile **file); +uint16 GetAiPurchaseCallbackResult(uint8 feature, CargoID cargo_type, uint8 default_selection, IndustryType src_industry, IndustryType dst_industry, uint8 distance, AIConstructionEvent event, uint8 count, uint8 station_size, const GRFFile **file); #endif /* NEWGRF_GENERIC_H */ diff --git a/src/newgrf_industries.cpp b/src/newgrf_industries.cpp index de051ad241..4e9c38743c 100644 --- a/src/newgrf_industries.cpp +++ b/src/newgrf_industries.cpp @@ -35,6 +35,12 @@ static uint32 _industry_creation_random_bits; IndustryOverrideManager _industry_mngr(NEW_INDUSTRYOFFSET, NUM_INDUSTRYTYPES, INVALID_INDUSTRYTYPE); IndustryTileOverrideManager _industile_mngr(NEW_INDUSTRYTILEOFFSET, NUM_INDUSTRYTILES, INVALID_INDUSTRYTILE); +/** + * Map the GRF local type to an industry type. + * @param grf_type The GRF local type. + * @param grf_id The GRF of the local type. + * @return The industry type in the global scope. + */ IndustryType MapNewGRFIndustryType(IndustryType grf_type, uint32 grf_id) { if (grf_type == IT_INVALID) return IT_INVALID; @@ -386,6 +392,16 @@ static void NewIndustryResolver(ResolverObject *res, TileIndex tile, Industry *i res->grffile = (indspec != NULL ? indspec->grf_prop.grffile : NULL); } +/** + * Perform an industry callback. + * @param callback The callback to perform. + * @param param1 The first parameter. + * @param param2 The second parameter. + * @param industry The industry to do the callback for. + * @param type The type of industry to do the callback for. + * @param tile The tile associated with the callback. + * @return The callback result. + */ uint16 GetIndustryCallback(CallbackID callback, uint32 param1, uint32 param2, Industry *industry, IndustryType type, TileIndex tile) { ResolverObject object; diff --git a/src/newgrf_railtype.cpp b/src/newgrf_railtype.cpp index 6f38794b6b..c381244648 100644 --- a/src/newgrf_railtype.cpp +++ b/src/newgrf_railtype.cpp @@ -87,6 +87,14 @@ static inline void NewRailTypeResolver(ResolverObject *res, TileIndex tile, Tile res->count = 0; } +/** + * Get the sprite to draw for the given tile. + * @param rti The rail type data (spec). + * @param tile The tile to get the sprite for. + * @param rtsg The type of sprite to draw. + * @param content Where are we drawing the tile? + * @return The sprite to draw. + */ SpriteID GetCustomRailSprite(const RailtypeInfo *rti, TileIndex tile, RailTypeSpriteGroup rtsg, TileContext context) { assert(rtsg < RTSG_END); @@ -104,6 +112,12 @@ SpriteID GetCustomRailSprite(const RailtypeInfo *rti, TileIndex tile, RailTypeSp return group->GetResult(); } +/** + * Perform a reverse railtype lookup to get the GRF internal ID. + * @param railtype The global (OpenTTD) railtype. + * @param grffile The GRF to do the lookup for. + * @return the GRF internal ID. + */ uint8 GetReverseRailTypeTranslation(RailType railtype, const GRFFile *grffile) { /* No rail type table present, return rail type as-is */ diff --git a/src/news_gui.cpp b/src/news_gui.cpp index a1e05d0746..8aa2ce6690 100644 --- a/src/news_gui.cpp +++ b/src/news_gui.cpp @@ -1392,6 +1392,9 @@ static const WindowDesc _message_options_desc( _nested_message_options_widgets, lengthof(_nested_message_options_widgets) ); +/** + * Show the settings window for news messages. + */ void ShowMessageOptions() { DeleteWindowById(WC_GAME_OPTIONS, 0); diff --git a/src/news_type.h b/src/news_type.h index f179f55517..edb475d400 100644 --- a/src/news_type.h +++ b/src/news_type.h @@ -119,6 +119,13 @@ struct NewsTypeData { NewsDisplay display; ///< Display mode (off, summary, full) const StringID description; ///< Description of the news type in news settings window + /** + * Construct this entry. + * @param name The name of the type. + * @param age The maximum age for these messages. + * @param sound The sound to play. + * @param description The description for this type of messages. + */ NewsTypeData(const char *name, byte age, SoundFx sound, StringID description) : name(name), age(age), @@ -129,6 +136,7 @@ struct NewsTypeData { } }; +/** Information about a single item of news. */ struct NewsItem { NewsItem *prev; ///< Previous news item NewsItem *next; ///< Next news item @@ -149,7 +157,7 @@ struct NewsItem { free(this->free_data); } - uint64 params[10]; + uint64 params[10]; ///< Parameters for string resolving. }; /** diff --git a/src/order_backup.cpp b/src/order_backup.cpp index 00645c8527..4a00a8c154 100644 --- a/src/order_backup.cpp +++ b/src/order_backup.cpp @@ -186,7 +186,7 @@ CommandCost CmdClearOrderBackup(TileIndex tile, DoCommandFlag flags, uint32 p1, /** * Reset the OrderBackups from GUI/game logic. - * @param tile The tile of the order backup. + * @param t The tile of the order backup. * @param from_gui Whether the call came from the GUI, i.e. whether * it must be synced over the network. */ diff --git a/src/order_backup.h b/src/order_backup.h index 51281e8608..583d4a853a 100644 --- a/src/order_backup.h +++ b/src/order_backup.h @@ -69,7 +69,17 @@ public: static void ClearVehicle(const Vehicle *v); }; +/** + * Iterator over all order backups from a given ID. + * @param var The variable to iterate with. + * @param start The start of the iteration. + */ #define FOR_ALL_ORDER_BACKUPS_FROM(var, start) FOR_ALL_ITEMS_FROM(OrderBackup, order_backup_index, var, start) + +/** + * Iterator over all order backups. + * @param var The variable to iterate with. + */ #define FOR_ALL_ORDER_BACKUPS(var) FOR_ALL_ORDER_BACKUPS_FROM(var, 0) #endif /* ORDER_BACKUP_H */ diff --git a/src/pathfinder/pf_performance_timer.hpp b/src/pathfinder/pf_performance_timer.hpp index 0f55575322..2f4662cbb6 100644 --- a/src/pathfinder/pf_performance_timer.hpp +++ b/src/pathfinder/pf_performance_timer.hpp @@ -12,7 +12,7 @@ #ifndef PF_PERFORMANCE_TIMER_HPP #define PF_PERFORMANCE_TIMER_HPP -extern uint64 ottd_rdtsc(); +#include "../debug.h" struct CPerformanceTimer { diff --git a/src/pathfinder/yapf/nodelist.hpp b/src/pathfinder/yapf/nodelist.hpp index 6a197f98da..b81fd65e00 100644 --- a/src/pathfinder/yapf/nodelist.hpp +++ b/src/pathfinder/yapf/nodelist.hpp @@ -151,9 +151,12 @@ public: return item; } + /** The number of items. */ FORCEINLINE int TotalCount() {return m_arr.Length();} + /** Get a particular item. */ FORCEINLINE Titem_& ItemAt(int idx) {return m_arr[idx];} + /** Helper for creating output of this array. */ template void Dump(D &dmp) const { dmp.WriteStructT("m_arr", &m_arr); diff --git a/src/pathfinder/yapf/yapf.h b/src/pathfinder/yapf/yapf.h index 37b3bf41ef..b02d9d0ee5 100644 --- a/src/pathfinder/yapf/yapf.h +++ b/src/pathfinder/yapf/yapf.h @@ -65,7 +65,7 @@ FindDepotData YapfRoadVehicleFindNearestDepot(const RoadVehicle *v, int max_pena /** * Used when user sends train to the nearest depot or if train needs servicing using YAPF. * @param v train that needs to go to some depot - * @param max_penalty max distance (int pathfinder penalty) from the current train position + * @param max_distance max distance (int pathfinder penalty) from the current train position * (used also as optimization - the pathfinder can stop path finding if max_penalty * was reached and no depot was seen) * @return the data about the depot diff --git a/src/pathfinder/yapf/yapf_costbase.hpp b/src/pathfinder/yapf/yapf_costbase.hpp index 29d6c85c26..057c0ae5b1 100644 --- a/src/pathfinder/yapf/yapf_costbase.hpp +++ b/src/pathfinder/yapf/yapf_costbase.hpp @@ -12,7 +12,14 @@ #ifndef YAPF_COSTBASE_HPP #define YAPF_COSTBASE_HPP +/** Base implementation for cost accounting. */ struct CYapfCostBase { + /** + * Does the given track direction on the given tile yeild an uphill penalty? + * @param tile The tile to check. + * @param td The track direction to check. + * @return True if there's a slope, otherwise false. + */ FORCEINLINE static bool stSlopeCost(TileIndex tile, Trackdir td) { if (IsDiagonalTrackdir(td)) { @@ -34,9 +41,4 @@ struct CYapfCostBase { } }; -struct CostRailSettings { - /* look-ahead signal penalty */ -}; - - #endif /* YAPF_COSTBASE_HPP */ diff --git a/src/pathfinder/yapf/yapf_costrail.hpp b/src/pathfinder/yapf/yapf_costrail.hpp index 0cee476993..f1b6565f23 100644 --- a/src/pathfinder/yapf/yapf_costrail.hpp +++ b/src/pathfinder/yapf/yapf_costrail.hpp @@ -17,7 +17,6 @@ template class CYapfCostRailT : public CYapfCostBase - , public CostRailSettings { public: typedef typename Types::Tpf Tpf; ///< the pathfinder class (derived from THIS class) diff --git a/src/pbs.h b/src/pbs.h index ec24477afe..2e1fb89680 100644 --- a/src/pbs.h +++ b/src/pbs.h @@ -30,7 +30,17 @@ struct PBSTileInfo { Trackdir trackdir; ///< The reserved trackdir on the tile. bool okay; ///< True if tile is a safe waiting position, false otherwise. + /** + * Create an empty PBSTileInfo. + */ PBSTileInfo() : tile(INVALID_TILE), trackdir(INVALID_TRACKDIR), okay(false) {} + + /** + * Create a PBSTileInfo with given tile, track direction and safe waiting position information. + * @param _t The tile where the path ends. + * @param _td The reserved track dir on the tile. + * @param _okay Whether the tile is a safe waiting point or not. + */ PBSTileInfo(TileIndex _t, Trackdir _td, bool _okay) : tile(_t), trackdir(_td), okay(_okay) {} }; diff --git a/src/sound/allegro_s.h b/src/sound/allegro_s.h index cca292b163..315bad2a83 100644 --- a/src/sound/allegro_s.h +++ b/src/sound/allegro_s.h @@ -14,6 +14,7 @@ #include "sound_driver.hpp" +/** Implementation of the allegro sound driver. */ class SoundDriver_Allegro: public SoundDriver { public: /* virtual */ const char *Start(const char * const *param); @@ -24,6 +25,7 @@ public: /* virtual */ const char *GetName() const { return "allegro"; } }; +/** Factory for the allegro sound driver. */ class FSoundDriver_Allegro: public SoundDriverFactory { public: static const int priority = 4; diff --git a/src/sound/null_s.h b/src/sound/null_s.h index 34f12e70e4..5951842cb7 100644 --- a/src/sound/null_s.h +++ b/src/sound/null_s.h @@ -14,6 +14,7 @@ #include "sound_driver.hpp" +/** Implementation of the null sound driver. */ class SoundDriver_Null: public SoundDriver { public: /* virtual */ const char *Start(const char * const *param) { return NULL; } @@ -22,6 +23,7 @@ public: /* virtual */ const char *GetName() const { return "null"; } }; +/** Factory for the null sound driver. */ class FSoundDriver_Null: public SoundDriverFactory { public: static const int priority = 1; diff --git a/src/sound/sdl_s.h b/src/sound/sdl_s.h index d8a4d587d4..6733ee6a76 100644 --- a/src/sound/sdl_s.h +++ b/src/sound/sdl_s.h @@ -14,6 +14,7 @@ #include "sound_driver.hpp" +/** Implementation of the SDL sound driver. */ class SoundDriver_SDL: public SoundDriver { public: /* virtual */ const char *Start(const char * const *param); @@ -22,6 +23,7 @@ public: /* virtual */ const char *GetName() const { return "sdl"; } }; +/** Factory for the SDL sound driver. */ class FSoundDriver_SDL: public SoundDriverFactory { public: static const int priority = 5; diff --git a/src/sound/sound_driver.hpp b/src/sound/sound_driver.hpp index c8225922cf..56664e6ad9 100644 --- a/src/sound/sound_driver.hpp +++ b/src/sound/sound_driver.hpp @@ -14,15 +14,21 @@ #include "../driver.h" +/** Base for all sound drivers. */ class SoundDriver: public Driver { public: - /* Called once every tick */ + /** Called once every tick */ virtual void MainLoop() {} }; +/** Base of the factory for the sound drivers. */ class SoundDriverFactoryBase: public DriverFactoryBase { }; +/** + * Factory for the sound drivers. + * @tparam T The type of the sound factory to register. + */ template class SoundDriverFactory: public SoundDriverFactoryBase { public: diff --git a/src/sound/win32_s.h b/src/sound/win32_s.h index c75d075940..03af04a534 100644 --- a/src/sound/win32_s.h +++ b/src/sound/win32_s.h @@ -14,6 +14,7 @@ #include "sound_driver.hpp" +/** Implementation of the sound driver for Windows. */ class SoundDriver_Win32: public SoundDriver { public: /* virtual */ const char *Start(const char * const *param); @@ -22,6 +23,7 @@ public: /* virtual */ const char *GetName() const { return "win32"; } }; +/** Factory for the sound driver for Windows. */ class FSoundDriver_Win32: public SoundDriverFactory { public: static const int priority = 10; diff --git a/src/video/allegro_v.h b/src/video/allegro_v.h index a48f17dda4..2760cbe46a 100644 --- a/src/video/allegro_v.h +++ b/src/video/allegro_v.h @@ -14,6 +14,7 @@ #include "video_driver.hpp" +/** The allegro video driver. */ class VideoDriver_Allegro: public VideoDriver { public: /* virtual */ const char *Start(const char * const *param); @@ -30,6 +31,7 @@ public: /* virtual */ const char *GetName() const { return "allegro"; } }; +/** Factory for the allegro video driver. */ class FVideoDriver_Allegro: public VideoDriverFactory { public: static const int priority = 4; diff --git a/src/video/dedicated_v.h b/src/video/dedicated_v.h index 7fd0c5391c..c06f050cdb 100644 --- a/src/video/dedicated_v.h +++ b/src/video/dedicated_v.h @@ -14,6 +14,7 @@ #include "video_driver.hpp" +/** The dedicated server video driver. */ class VideoDriver_Dedicated: public VideoDriver { public: /* virtual */ const char *Start(const char * const *param); @@ -30,6 +31,7 @@ public: /* virtual */ const char *GetName() const { return "dedicated"; } }; +/** Factory for the dedicated server video driver. */ class FVideoDriver_Dedicated: public VideoDriverFactory { public: #ifdef DEDICATED diff --git a/src/video/null_v.h b/src/video/null_v.h index f9329d2d66..fa0ff054fa 100644 --- a/src/video/null_v.h +++ b/src/video/null_v.h @@ -14,9 +14,10 @@ #include "video_driver.hpp" +/** The null video driver. */ class VideoDriver_Null: public VideoDriver { private: - uint ticks; + uint ticks; ///< Amount of ticks to run. public: /* virtual */ const char *Start(const char * const *param); @@ -33,6 +34,7 @@ public: /* virtual */ const char *GetName() const { return "null"; } }; +/** Factory the null video driver. */ class FVideoDriver_Null: public VideoDriverFactory { public: static const int priority = 0; diff --git a/src/video/sdl_v.h b/src/video/sdl_v.h index 4d2faf9fe0..c7f5b84c36 100644 --- a/src/video/sdl_v.h +++ b/src/video/sdl_v.h @@ -14,6 +14,7 @@ #include "video_driver.hpp" +/** The SDL video driver. */ class VideoDriver_SDL: public VideoDriver { public: /* virtual */ const char *Start(const char * const *param); @@ -30,6 +31,7 @@ public: /* virtual */ const char *GetName() const { return "sdl"; } }; +/** Factory for the SDL video driver. */ class FVideoDriver_SDL: public VideoDriverFactory { public: static const int priority = 5; diff --git a/src/video/video_driver.hpp b/src/video/video_driver.hpp index f8defcca28..1e647cb1c4 100644 --- a/src/video/video_driver.hpp +++ b/src/video/video_driver.hpp @@ -15,20 +15,47 @@ #include "../driver.h" #include "../core/geometry_type.hpp" +/** The base of all video drivers. */ class VideoDriver: public Driver { public: + /** + * Mark a particular area dirty. + * @param left The left most line of the dirty area. + * @param top The top most line of the dirty area. + * @param width The width of the dirty area. + * @param height The height of the dirty area. + */ virtual void MakeDirty(int left, int top, int width, int height) = 0; + /** + * Perform the actual drawing. + */ virtual void MainLoop() = 0; + /** + * Change the resolution of the window. + * @param w The new width. + * @param h The new height. + * @return True if the change succeeded. + */ virtual bool ChangeResolution(int w, int h) = 0; + /** + * Change the full screen setting. + * @param fullscreen The new setting. + * @return True if the change succeeded. + */ virtual bool ToggleFullscreen(bool fullscreen) = 0; }; +/** Base of the factory for the video drivers. */ class VideoDriverFactoryBase: public DriverFactoryBase { }; +/** + * Factory for the video drivers. + * @tparam T The type of the video factory to register. + */ template class VideoDriverFactory: public VideoDriverFactoryBase { public: diff --git a/src/video/win32_v.cpp b/src/video/win32_v.cpp index 84f1967ffd..5fdd3dab6b 100644 --- a/src/video/win32_v.cpp +++ b/src/video/win32_v.cpp @@ -224,6 +224,11 @@ static void CALLBACK TrackMouseTimerProc(HWND hwnd, UINT msg, UINT event, DWORD } } +/** + * Instantiate a new window. + * @param full_screen Whether to make a full screen window or not. + * @return True if the window could be created. + */ bool VideoDriver_Win32::MakeWindow(bool full_screen) { _fullscreen = full_screen; diff --git a/src/video/win32_v.h b/src/video/win32_v.h index 4e267b2ab0..3e714b38a5 100644 --- a/src/video/win32_v.h +++ b/src/video/win32_v.h @@ -14,6 +14,7 @@ #include "video_driver.hpp" +/** The video driver for windows. */ class VideoDriver_Win32: public VideoDriver { public: /* virtual */ const char *Start(const char * const *param); @@ -32,6 +33,7 @@ public: bool MakeWindow(bool full_screen); }; +/** The factory for Windows' video driver. */ class FVideoDriver_Win32: public VideoDriverFactory { public: static const int priority = 10;