From 097b3b3c7bdca1f8e6d0180433911e2424c1e03e Mon Sep 17 00:00:00 2001 From: belugas Date: Tue, 17 Apr 2007 20:23:13 +0000 Subject: [PATCH] (svn r9662) -Documentation: Doxygen corrections and @file omissions --- src/engine.cpp | 2 ++ src/engine.h | 2 +- src/fios.cpp | 5 ++--- src/genworld_gui.cpp | 4 ++-- src/gfx.cpp | 10 +++++----- src/helpers.cpp | 4 ++-- src/main_gui.cpp | 3 ++- src/misc/array.hpp | 2 ++ src/misc/autocopyptr.hpp | 2 ++ src/misc/autoptr.hpp | 2 ++ src/misc/binaryheap.hpp | 2 ++ src/misc/blob.hpp | 2 ++ src/misc/countedptr.hpp | 2 ++ src/misc/crc32.hpp | 2 ++ src/misc/fixedsizearray.hpp | 2 ++ src/misc/hashtable.hpp | 4 +++- src/misc_cmd.cpp | 9 +++++++++ src/misc_gui.cpp | 30 ++++++++++++++++-------------- src/music/bemidi.cpp | 2 ++ src/music/dmusic.cpp | 33 +++++++++++++++++---------------- src/newgrf.cpp | 7 ++++--- src/newgrf_config.cpp | 3 ++- src/newgrf_engine.cpp | 2 +- src/newgrf_station.cpp | 12 +++++++----- src/newgrf_text.cpp | 4 ++-- src/news_gui.cpp | 16 ++++++++-------- src/order_cmd.cpp | 8 ++++++++ src/spritecache.cpp | 2 +- src/stdafx.h | 2 +- src/widget.cpp | 20 ++++++++------------ src/window.cpp | 2 +- 31 files changed, 122 insertions(+), 80 deletions(-) diff --git a/src/engine.cpp b/src/engine.cpp index 862c0b10d6..4a0b271615 100644 --- a/src/engine.cpp +++ b/src/engine.cpp @@ -249,6 +249,7 @@ void EnginesDailyLoop() /** Accept an engine prototype. XXX - it is possible that the top-player * changes while you are waiting to accept the offer? Then it becomes invalid * @param tile unused + * @param flags operation to perfom * @param p1 engine-prototype offered * @param p2 unused */ @@ -350,6 +351,7 @@ void EnginesMonthlyLoop() /** Rename an engine. * @param tile unused + * @param flags operation to perfom * @param p1 engine ID to rename * @param p2 unused */ diff --git a/src/engine.h b/src/engine.h index 192d7399a2..4aed679946 100644 --- a/src/engine.h +++ b/src/engine.h @@ -295,7 +295,7 @@ typedef EngineRenew* EngineRenewList; /** * Remove all engine replacement settings for the player. - * @param er The renewlist for a given player. + * @param erl The renewlist for a given player. * @return The new renewlist for the player. */ void RemoveAllEngineReplacement(EngineRenewList* erl); diff --git a/src/fios.cpp b/src/fios.cpp index 3ba326dfce..73e2b3ad56 100644 --- a/src/fios.cpp +++ b/src/fios.cpp @@ -57,7 +57,7 @@ FiosItem *FiosAlloc() /** * Compare two FiosItem's. Used with qsort when sorting the file list. * @param a A pointer to the first FiosItem to compare. - * @param a A pointer to the second FiosItem to compare. + * @param b A pointer to the second FiosItem to compare. * @return -1, 0 or 1, depending on how the two items should be sorted. */ int CDECL compare_FiosItems(const void *a, const void *b) @@ -200,9 +200,8 @@ bool FileExists(const char *filename) typedef byte fios_getlist_callback_proc(int mode, const char *filename, const char *ext, char *title); /** Create a list of the files in a directory, according to some arbitrary rule. - * @param num Will be filled with the amount of items. * @param mode The mode we are in. Some modes don't allow 'parent'. - * @param callback The function that is called where you need to do the filtering. + * @param callback_proc The function that is called where you need to do the filtering. * @return Return the list of files. */ static FiosItem *FiosGetFileList(int mode, fios_getlist_callback_proc *callback_proc) { diff --git a/src/genworld_gui.cpp b/src/genworld_gui.cpp index 55817304bf..b78f14ea5e 100644 --- a/src/genworld_gui.cpp +++ b/src/genworld_gui.cpp @@ -899,7 +899,7 @@ static void _SetGeneratingWorldProgress(gwp_class cls, uint progress, uint total /** * Set the total of a stage of the world generation. - * @param class the current class we are in. + * @param cls the current class we are in. * @param total Set the total expected items for this class. * * Warning: this function isn't clever. Don't go from class 4 to 3. Go upwards, always. @@ -914,7 +914,7 @@ void SetGeneratingWorldProgress(gwp_class cls, uint total) /** * Increases the current stage of the world generation with one. - * @param class the current class we are in. + * @param cls the current class we are in. * * Warning: this function isn't clever. Don't go from class 4 to 3. Go upwards, always. * Also, progress works if total is zero, total works if progress is zero. diff --git a/src/gfx.cpp b/src/gfx.cpp index f00ee53617..30b305d632 100644 --- a/src/gfx.cpp +++ b/src/gfx.cpp @@ -275,7 +275,7 @@ void GfxDrawLine(int x, int y, int x2, int y2, int color) /** Truncate a given string to a maximum width if neccessary. * If the string is truncated, add three dots ('...') to show this. - * @param *dest string that is checked and possibly truncated + * @param *str string that is checked and possibly truncated * @param maxw maximum width in pixels of the string * @return new width of (truncated) string */ static int TruncateString(char *str, int maxw) @@ -413,11 +413,11 @@ void DrawStringCenterUnderlineTruncated(int xl, int xr, int y, StringID str, uin /** 'Correct' a string to a maximum length. Longer strings will be cut into * additional lines at whitespace characters if possible. The string parameter * is modified with terminating characters mid-string which are the - * placeholders for the newlines.
+ * placeholders for the newlines. * The string WILL be truncated if there was no whitespace for the current * line's maximum width. * - * @note To know if the the terminating '\0' is the string end or just a + * @note To know if the terminating '\0' is the string end or just a * newline, the returned 'num' value should be consulted. The num'th '\0', * starting with index 0 is the real string end. * @@ -487,7 +487,7 @@ end_of_inner_loop: * @param x Centre the string around this pixel width * @param y Draw the string at this pixel height (first line's bottom) * @param str String to draw - * @param max Maximum width the string can have before it is wrapped */ + * @param maxw Maximum width the string can have before it is wrapped */ void DrawStringMultiCenter(int x, int y, StringID str, int maxw) { char buffer[512]; @@ -626,7 +626,7 @@ BoundingRect GetStringBoundingBox(const char *str) /** Draw a string at the given coordinates with the given colour * @param string the string to draw * @param x offset from left side of the screen, if negative offset from the right side - * @param x offset from top side of the screen, if negative offset from the bottom + * @param y offset from top side of the screen, if negative offset from the bottom * @param real_color colour of the string, see _string_colormap in * table/palettes.h or docs/ottd-colourtext-palette.png * @return the x-coordinates where the drawing has finished. If nothing is drawn diff --git a/src/helpers.cpp b/src/helpers.cpp index c898003a69..4caf7927fc 100644 --- a/src/helpers.cpp +++ b/src/helpers.cpp @@ -44,7 +44,7 @@ uint EngList_Count(const EngineList *el) /** Add new item at the end of Engine List * @param el list o which to add an engine - * @param eif engine to add to the list + * @param eid engine to add to the list */ void EngList_Add(EngineList *el, EngineID eid) { @@ -81,7 +81,7 @@ void EngList_Sort(EngineList *el, EngList_SortTypeFunction compare) * @param el list to be sorted * @param compare function for evaluation of the quicksort * @param begin start of sorting - * @param count of items to be sorted + * @param num_items count of items to be sorted */ void EngList_SortPartial(EngineList *el, EngList_SortTypeFunction compare, uint begin, uint num_items) { diff --git a/src/main_gui.cpp b/src/main_gui.cpp index e23e8bddd9..8075911712 100644 --- a/src/main_gui.cpp +++ b/src/main_gui.cpp @@ -1247,7 +1247,8 @@ static OnButtonClick * const _editor_terraform_button_proc[] = { /** Callback function for the scenario editor 'reset landscape' confirmation window - * @param yes_clicked boolean value, true when yes was clicked, false otherwise */ + * @param w Window unused + * @param confirmed boolean value, true when yes was clicked, false otherwise */ static void ResetLandscapeConfirmationCallback(Window *w, bool confirmed) { if (confirmed) { diff --git a/src/misc/array.hpp b/src/misc/array.hpp index e8eff1c8c9..7f8e423295 100644 --- a/src/misc/array.hpp +++ b/src/misc/array.hpp @@ -1,5 +1,7 @@ /* $Id$ */ +/** @file array.hpp */ + #ifndef ARRAY_HPP #define ARRAY_HPP diff --git a/src/misc/autocopyptr.hpp b/src/misc/autocopyptr.hpp index b5ca6ddd1a..0c684aac26 100644 --- a/src/misc/autocopyptr.hpp +++ b/src/misc/autocopyptr.hpp @@ -1,5 +1,7 @@ /* $Id$ */ +/** @file autocopyptr.hpp */ + #ifndef AUTOCOPYPTR_HPP #define AUTOCOPYPTR_HPP diff --git a/src/misc/autoptr.hpp b/src/misc/autoptr.hpp index 3412f3bbc0..08516d2ea7 100644 --- a/src/misc/autoptr.hpp +++ b/src/misc/autoptr.hpp @@ -1,5 +1,7 @@ /* $Id$ */ +/** @file autoptr.hpp */ + #ifndef AUTOPTR_HPP #define AUTOPTR_HPP diff --git a/src/misc/binaryheap.hpp b/src/misc/binaryheap.hpp index 7b72a25af3..78ebdc47fc 100644 --- a/src/misc/binaryheap.hpp +++ b/src/misc/binaryheap.hpp @@ -1,5 +1,7 @@ /* $Id$ */ +/** @file binaryheap.hpp */ + #ifndef BINARYHEAP_HPP #define BINARYHEAP_HPP diff --git a/src/misc/blob.hpp b/src/misc/blob.hpp index 1a20f3ac28..97bd011601 100644 --- a/src/misc/blob.hpp +++ b/src/misc/blob.hpp @@ -1,5 +1,7 @@ /* $Id$ */ +/** @file blob.hpp */ + #ifndef BLOB_HPP #define BLOB_HPP diff --git a/src/misc/countedptr.hpp b/src/misc/countedptr.hpp index e63e47fb5a..0d6a925b84 100644 --- a/src/misc/countedptr.hpp +++ b/src/misc/countedptr.hpp @@ -1,5 +1,7 @@ /* $Id$ */ +/** @file countedptr.hpp */ + #ifndef COUNTEDPTR_HPP #define COUNTEDPTR_HPP diff --git a/src/misc/crc32.hpp b/src/misc/crc32.hpp index 10e9a7ac49..71f7ff03fe 100644 --- a/src/misc/crc32.hpp +++ b/src/misc/crc32.hpp @@ -1,5 +1,7 @@ /* $Id$ */ +/** @file crc32.hpp */ + #ifndef CRC32_HPP #define CRC32_HPP diff --git a/src/misc/fixedsizearray.hpp b/src/misc/fixedsizearray.hpp index 48b177f3c0..ee4ea14ca0 100644 --- a/src/misc/fixedsizearray.hpp +++ b/src/misc/fixedsizearray.hpp @@ -1,5 +1,7 @@ /* $Id$ */ +/** @file fixedsizearray.hpp */ + #ifndef FIXEDSIZEARRAY_HPP #define FIXEDSIZEARRAY_HPP diff --git a/src/misc/hashtable.hpp b/src/misc/hashtable.hpp index c6b52e50a6..fad44114df 100644 --- a/src/misc/hashtable.hpp +++ b/src/misc/hashtable.hpp @@ -1,5 +1,7 @@ /* $Id$ */ +/** @file hashtable.hpp */ + #ifndef HASHTABLE_HPP #define HASHTABLE_HPP @@ -97,7 +99,7 @@ struct CHashTableSlotT } }; -/** @class CHashTableT - simple hash table +/** class CHashTableT - simple hash table * of pointers allocated elsewhere. * * Supports: Add/Find/Remove of Titems. diff --git a/src/misc_cmd.cpp b/src/misc_cmd.cpp index 59824a1acb..a4be0588b5 100644 --- a/src/misc_cmd.cpp +++ b/src/misc_cmd.cpp @@ -38,6 +38,7 @@ int32 CmdSetPlayerFace(TileIndex tile, uint32 flags, uint32 p1, uint32 p2) /** Change the player's company-colour * @param tile unused + * @param flags operation to perform * @param p1 bitstuffed: * p1 bits 0-7 scheme to set * p1 bits 8-9 set in use state or first/second colour @@ -117,6 +118,7 @@ int32 CmdSetPlayerColor(TileIndex tile, uint32 flags, uint32 p1, uint32 p2) /** Increase the loan of your company. * @param tile unused + * @param flags operation to perform * @param p1 unused * @param p2 when set, loans the maximum amount in one go (press CTRL) */ @@ -146,6 +148,7 @@ int32 CmdIncreaseLoan(TileIndex tile, uint32 flags, uint32 p1, uint32 p2) /** Decrease the loan of your company. * @param tile unused + * @param flags operation to perform * @param p1 unused * @param p2 when set, pays back the maximum loan permitting money (press CTRL) */ @@ -186,6 +189,7 @@ int32 CmdDecreaseLoan(TileIndex tile, uint32 flags, uint32 p1, uint32 p2) /** Change the name of the company. * @param tile unused + * @param flags operation to perform * @param p1 unused * @param p2 unused */ @@ -213,6 +217,7 @@ int32 CmdChangeCompanyName(TileIndex tile, uint32 flags, uint32 p1, uint32 p2) /** Change the name of the president. * @param tile unused + * @param flags operation to perform * @param p1 unused * @param p2 unused */ @@ -251,6 +256,7 @@ int32 CmdChangePresidentName(TileIndex tile, uint32 flags, uint32 p1, uint32 p2) * the game is unpaused. A counter is used instead of a boolean value * to have more control over the game when saving/loading, etc. * @param tile unused + * @param flags operation to perform * @param p1 0 = decrease pause counter; 1 = increase pause counter * @param p2 unused */ @@ -269,6 +275,7 @@ int32 CmdPause(TileIndex tile, uint32 flags, uint32 p1, uint32 p2) * This is normally only enabled in offline mode, but if there is a debug * build, you can cheat (to test). * @param tile unused + * @param flags operation to perform * @param p1 the amount of money to receive (if negative), or spend (if positive) * @param p2 unused */ @@ -286,6 +293,7 @@ int32 CmdMoneyCheat(TileIndex tile, uint32 flags, uint32 p1, uint32 p2) * players if you have paid off your loan (either explicitely, or implicitely * given the fact that you have more money than loan). * @param tile unused + * @param flags operation to perform * @param p1 the amount of money to transfer; max 20.000.000 * @param p2 the player to transfer the money to */ @@ -317,6 +325,7 @@ int32 CmdGiveMoney(TileIndex tile, uint32 flags, uint32 p1, uint32 p2) * in file 'settings_gui.c' _game_setting_info[]; we'll just trust the server it knows * what to do and does this correctly * @param tile unused + * @param flags operation to perform * @param p1 the difficulty setting being changed. If it is -1, the difficulty level * itself is changed. The new value is inside p2 * @param p2 new value for a difficulty setting or difficulty level diff --git a/src/misc_gui.cpp b/src/misc_gui.cpp index 9bc7ab1c9e..c22043913d 100644 --- a/src/misc_gui.cpp +++ b/src/misc_gui.cpp @@ -677,9 +677,10 @@ static void TooltipsWndProc(Window *w, WindowEvent *e) } /** Shows a tooltip -* @param str String to be displayed -* @param params (optional) up to 5 pieces of additional information that may be -* added to a tooltip; currently only supports parameters of {NUM} (integer) */ + * @param str String to be displayed + * @param paramcount number of params to deal with + * @param params (optional) up to 5 pieces of additional information that may be + * added to a tooltip; currently only supports parameters of {NUM} (integer) */ void GuiShowTooltipsWithArgs(StringID str, uint paramcount, const uint32 params[]) { char buffer[512]; @@ -824,8 +825,8 @@ static void DelChar(Textbuf *tb, bool backspace) /** * Delete a character from a textbuffer, either with 'Delete' or 'Backspace' * The character is delete from the position the caret is at - * @param tb @Textbuf type to be changed - * @param delmode Type of deletion, either @WKC_BACKSPACE or @WKC_DELETE + * @param tb Textbuf type to be changed + * @param delmode Type of deletion, either WKC_BACKSPACE or WKC_DELETE * @return Return true on successfull change of Textbuf, or false otherwise */ bool DeleteTextBufferChar(Textbuf *tb, int delmode) @@ -843,7 +844,7 @@ bool DeleteTextBufferChar(Textbuf *tb, int delmode) /** * Delete every character in the textbuffer - * @param tb @Textbuf buffer to be emptied + * @param tb Textbuf buffer to be emptied */ void DeleteTextBufferAll(Textbuf *tb) { @@ -856,7 +857,7 @@ void DeleteTextBufferAll(Textbuf *tb) * Insert a character to a textbuffer. If maxwidth of the Textbuf is zero, * we don't care about the visual-length but only about the physical * length of the string - * @param tb @Textbuf type to be changed + * @param tb Textbuf type to be changed * @param key Character to be inserted * @return Return true on successfull change of Textbuf, or false otherwise */ @@ -880,8 +881,8 @@ bool InsertTextBufferChar(Textbuf *tb, WChar key) /** * Handle text navigation with arrow keys left/right. * This defines where the caret will blink and the next characer interaction will occur - * @param tb @Textbuf type where navigation occurs - * @param navmode Direction in which navigation occurs @WKC_LEFT, @WKC_RIGHT, @WKC_END, @WKC_HOME + * @param tb Textbuf type where navigation occurs + * @param navmode Direction in which navigation occurs WKC_LEFT, WKC_RIGHT, WKC_END, WKC_HOME * @return Return true on successfull change of Textbuf, or false otherwise */ bool MoveTextBufferPos(Textbuf *tb, int navmode) @@ -924,7 +925,7 @@ bool MoveTextBufferPos(Textbuf *tb, int navmode) /** * Initialize the textbuffer by supplying it the buffer to write into * and the maximum length of this buffer - * @param tb @Textbuf type which is getting initialized + * @param tb Textbuf type which is getting initialized * @param buf the buffer that will be holding the data for input * @param maxlength maximum length in characters of this buffer * @param maxwidth maximum length in pixels of this buffer. If reached, buffer @@ -940,10 +941,10 @@ void InitializeTextBuffer(Textbuf *tb, const char *buf, uint16 maxlength, uint16 } /** - * Update @Textbuf type with its actual physical character and screenlength + * Update Textbuf type with its actual physical character and screenlength * Get the count of characters in the string as well as the width in pixels. * Useful when copying in a larger amount of text at once - * @param tb @Textbuf type which length is calculated + * @param tb Textbuf type which length is calculated */ void UpdateTextBufferSize(Textbuf *tb) { @@ -1271,8 +1272,7 @@ static const WindowDesc _query_desc = { * @param message string that will be shown for the window * @param parent pointer to parent window, if this pointer is NULL the parent becomes * the main window WC_MAIN_WINDOW - * @param x,y coordinates to show the window at - * @param yes_no_callback callback function called when window is closed through any button */ + * @param callback callback function pointer to set in the window descriptor*/ void ShowQuery(StringID caption, StringID message, Window *parent, void (*callback)(Window*, bool)) { Window *w = AllocateWindowDesc(&_query_desc); @@ -1722,6 +1722,7 @@ static int32 ClickChangePlayerCheat(int32 p1, int32 p2) /** * @param p1 -1 or +1 (down/up) + * @param p2 unused */ static int32 ClickChangeClimateCheat(int32 p1, int32 p2) { @@ -1735,6 +1736,7 @@ static int32 ClickChangeClimateCheat(int32 p1, int32 p2) extern void EnginesMonthlyLoop(); /** + * @param p1 unused * @param p2 1 (increase) or -1 (decrease) */ static int32 ClickChangeDateCheat(int32 p1, int32 p2) diff --git a/src/music/bemidi.cpp b/src/music/bemidi.cpp index be8535d895..0cf500a507 100644 --- a/src/music/bemidi.cpp +++ b/src/music/bemidi.cpp @@ -1,5 +1,7 @@ /* $Id$ */ +/** @file bemidi.cpp */ + #include "../stdafx.h" #include "../openttd.h" #include "bemidi.h" diff --git a/src/music/dmusic.cpp b/src/music/dmusic.cpp index 3846878cd1..f0538c6781 100644 --- a/src/music/dmusic.cpp +++ b/src/music/dmusic.cpp @@ -1,5 +1,7 @@ /* $Id$ */ +/** @file dmusic.cpp */ + #ifdef WIN32_ENABLE_DIRECTMUSIC_SUPPORT #include "../stdafx.h" @@ -14,13 +16,13 @@ #include -// the performance object controls manipulation of the segments +/** the performance object controls manipulation of the segments */ static IDirectMusicPerformance* performance = NULL; -// the loader object can load many types of DMusic related files +/** the loader object can load many types of DMusic related files */ static IDirectMusicLoader* loader = NULL; -// the segment object is where the MIDI data is stored for playback +/** the segment object is where the MIDI data is stored for playback */ static IDirectMusicSegment* segment = NULL; static bool seeking = false; @@ -54,12 +56,12 @@ static const char* DMusicMidiStart(const char* const* parm) return "ole32.dll load failed"; } - // Initialize COM + /* Initialize COM */ if (FAILED(proc.CoInitialize(NULL))) { return "COM initialization failed"; } - // create the performance object + /* create the performance object */ if (FAILED(proc.CoCreateInstance( CLSID_DirectMusicPerformance, NULL, @@ -71,7 +73,7 @@ static const char* DMusicMidiStart(const char* const* parm) return "Failed to create the performance object"; } - // initialize it + /* initialize it */ if (FAILED(performance->Init(NULL, NULL, NULL))) { performance->Release(); performance = NULL; @@ -79,7 +81,7 @@ static const char* DMusicMidiStart(const char* const* parm) return "Failed to initialize performance object"; } - // choose default Windows synth + /* choose default Windows synth */ if (FAILED(performance->AddPort(NULL))) { performance->CloseDown(); performance->Release(); @@ -88,7 +90,7 @@ static const char* DMusicMidiStart(const char* const* parm) return "AddPort failed"; } - // create the loader object; this will be used to load the MIDI file + /* create the loader object; this will be used to load the MIDI file */ if (FAILED(proc.CoCreateInstance( CLSID_DirectMusicLoader, NULL, @@ -136,7 +138,7 @@ static void DMusicMidiStop() static void DMusicMidiPlaySong(const char* filename) { - // set up the loader object info + /* set up the loader object info */ DMUS_OBJECTDESC obj_desc; ZeroMemory(&obj_desc, sizeof(obj_desc)); obj_desc.dwSize = sizeof(obj_desc); @@ -148,13 +150,13 @@ static void DMusicMidiPlaySong(const char* filename) obj_desc.wszFileName, lengthof(obj_desc.wszFileName) ); - // release the existing segment if we have any + /* release the existing segment if we have any */ if (segment != NULL) { segment->Release(); segment = NULL; } - // make a new segment + /* make a new segment */ if (FAILED(loader->GetObject( &obj_desc, IID_IDirectMusicSegment, (LPVOID*)&segment ))) { @@ -162,7 +164,7 @@ static void DMusicMidiPlaySong(const char* filename) return; } - // tell the segment what kind of data it contains + /* tell the segment what kind of data it contains */ if (FAILED(segment->SetParam( GUID_StandardMIDIFile, 0xFFFFFFFF, 0, 0, performance ))) { @@ -170,13 +172,13 @@ static void DMusicMidiPlaySong(const char* filename) return; } - // tell the segment to 'download' the instruments + /* tell the segment to 'download' the instruments */ if (FAILED(segment->SetParam(GUID_Download, 0xFFFFFFFF, 0, 0, performance))) { DEBUG(driver, 0, "DirectMusic: failed to download instruments"); return; } - // start playing the MIDI file + /* start playing the MIDI file */ if (FAILED(performance->PlaySegment(segment, 0, 0, NULL))) { DEBUG(driver, 0, "DirectMusic: PlaySegment failed"); return; @@ -210,8 +212,7 @@ static bool DMusicMidiIsSongPlaying() static void DMusicMidiSetVolume(byte vol) { - // 0 - 127 -> -2000 - 0 - long db = vol * 2000 / 127 - 2000; + long db = vol * 2000 / 127 - 2000; ///< 0 - 127 -> -2000 - 0 performance->SetGlobalParam(GUID_PerfMasterVolume, &db, sizeof(db)); } diff --git a/src/newgrf.cpp b/src/newgrf.cpp index c7edcdadee..235b28ae17 100644 --- a/src/newgrf.cpp +++ b/src/newgrf.cpp @@ -136,7 +136,7 @@ static uint32 _grm_engines[TOTAL_NUM_ENGINES]; * loading/parsing grf files, not for runtime debug messages as there * is no file information available during that time. * @param severity debugging severity level, see debug.h - * @param debugging message in printf() format */ + * @param str message in printf() format */ void CDECL grfmsg(int severity, const char *str, ...) { char buf[1024]; @@ -234,6 +234,7 @@ static GRFFile *GetFileByFilename(const char *filename) /** Used when setting an object's property to map to the GRF's strings * while taking in consideration the "drift" between TTDPatch string system and OpenTTD's one + * @param grfid Id of the grf file * @param str StringID that we want to have the equivalent in OoenTTD * @return the properly adjusted StringID */ @@ -2004,8 +2005,8 @@ static const SpriteGroup* NewCallBackResultSpriteGroup(uint16 value) /** * Creates a spritegroup representing a sprite number result. - * @param value The sprite number. - * @param sprites The number of sprites per set. + * @param sprite The sprite number. + * @param num_sprites The number of sprites per set. * @return A spritegroup representing the sprite number result. */ static const SpriteGroup* NewResultSpriteGroup(SpriteID sprite, byte num_sprites) diff --git a/src/newgrf_config.cpp b/src/newgrf_config.cpp index 74c4ba525a..6b58074964 100644 --- a/src/newgrf_config.cpp +++ b/src/newgrf_config.cpp @@ -187,7 +187,8 @@ void AppendStaticGRFConfigs(GRFConfig **dst) } /** Appends an element to a list of GRFs - * @param dst the head of the list to add to */ + * @param dst the head of the list to add to + * @param el the new tail to be */ void AppendToGRFConfigList(GRFConfig **dst, GRFConfig *el) { GRFConfig **tail = dst; diff --git a/src/newgrf_engine.cpp b/src/newgrf_engine.cpp index 6fd836631a..a75107f66e 100644 --- a/src/newgrf_engine.cpp +++ b/src/newgrf_engine.cpp @@ -886,7 +886,7 @@ bool UsesWagonOverride(const Vehicle* v) * @param param1 First parameter of the callback * @param param2 Second parameter of the callback * @param engine Engine type of the vehicle to evaluate the callback for - * @param vehicle The vehicle to evaluate the callback for, or NULL if it doesnt exist yet + * @param v The vehicle to evaluate the callback for, or NULL if it doesnt exist yet * @return The value the callback returned, or CALLBACK_FAILED if it failed */ uint16 GetVehicleCallback(uint16 callback, uint32 param1, uint32 param2, EngineID engine, const Vehicle *v) diff --git a/src/newgrf_station.cpp b/src/newgrf_station.cpp index eb9757f164..3212a75e26 100644 --- a/src/newgrf_station.cpp +++ b/src/newgrf_station.cpp @@ -61,7 +61,7 @@ void ResetStationClasses() /** * Allocate a station class for the given class id. - * @param classid A 32 bit value identifying the class. + * @param cls A 32 bit value identifying the class. * @return Index into station_classes of allocated class. */ StationClassID AllocateStationClass(uint32 cls) @@ -138,7 +138,7 @@ uint GetNumCustomStations(StationClassID sclass) /** * Tie a station spec to its station class. - * @param spec The station spec. + * @param statspec The station spec. */ void SetCustomStationSpec(StationSpec *statspec) { @@ -614,7 +614,7 @@ uint16 GetStationCallback(uint16 callback, uint32 param1, uint32 param2, const S /** * Allocate a StationSpec to a Station. This is called once per build operation. - * @param spec StationSpec to allocate. + * @param statspec StationSpec to allocate. * @param st Station to allocate it to. * @param exec Whether to actually allocate the spec. * @return Index within the Station's spec list, or -1 if the allocation failed. @@ -695,10 +695,12 @@ void DeallocateSpecFromStation(Station* st, byte specindex) } /** Draw representation of a station tile for GUI purposes. - * @param x, y Position of image. - * @param dir Direction. + * @param x Position x of image. + * @param y Position y of image. + * @param axis Axis. * @param railtype Rail type. * @param sclass, station Type of station. + * @param station station ID * @return True if the tile was drawn (allows for fallback to default graphic) */ bool DrawStationTile(int x, int y, RailType railtype, Axis axis, StationClassID sclass, uint station) diff --git a/src/newgrf_text.cpp b/src/newgrf_text.cpp index 8f44577916..0c5208cff0 100644 --- a/src/newgrf_text.cpp +++ b/src/newgrf_text.cpp @@ -418,8 +418,8 @@ char *GetGRFString(char *buff, uint16 stringid, const char* last) * The array iso_codes will be used to find that match. * If not found, it will have to be standard english * This function is called after the user changed language, - * from strings.c:ReadLanguagePack - * @param iso code of current selection + * from strings.cpp:ReadLanguagePack + * @param iso_name iso code of current selection */ void SetCurrentGrfLangID(const char *iso_name) { diff --git a/src/news_gui.cpp b/src/news_gui.cpp index a94461180a..0bfb21b4c5 100644 --- a/src/news_gui.cpp +++ b/src/news_gui.cpp @@ -240,17 +240,17 @@ static inline NewsID decreaseIndex(NewsID i) * @param flags various control bits that will show various news-types. See macro NEWS_FLAGS() * @param data_a news-specific value based on news type * @param data_b news-specific value based on news type - * @note flags exists of 4 byte-sized extra parameters.
- * 1. 0 - 7 display_mode, any of the NewsMode enums (NM_)
- * 2. 8 - 15 news flags, any of the NewsFlags enums (NF_) NF_INCOLOR are set automatically if needed
- * 3. 16 - 23 news category, any of the NewsType enums (NT_)
- * 4. 24 - 31 news callback function, any of the NewsCallback enums (DNC_)
+ * @note flags exists of 4 byte-sized extra parameters. + * 1. 0 - 7 display_mode, any of the NewsMode enums (NM_) + * 2. 8 - 15 news flags, any of the NewsFlags enums (NF_) NF_INCOLOR are set automatically if needed + * 3. 16 - 23 news category, any of the NewsType enums (NT_) + * 4. 24 - 31 news callback function, any of the NewsCallback enums (DNC_) * If the display mode is NM_CALLBACK special news is shown and parameter - * stringid has a special meaning.
+ * stringid has a special meaning. * DNC_TRAINAVAIL, DNC_ROADAVAIL, DNC_SHIPAVAIL, DNC_AIRCRAFTAVAIL: StringID is - * the index of the engine that is shown
+ * the index of the engine that is shown * DNC_BANKRUPCY: bytes 0-3 of StringID contains the player that is in trouble, - * and 4-7 contains what kind of bankrupcy message is shown, NewsBankrupcy enum (NB_)
+ * and 4-7 contains what kind of bankrupcy message is shown, NewsBankrupcy enum (NB_) * @see NewsMode * @see NewsFlags * @see NewsType diff --git a/src/order_cmd.cpp b/src/order_cmd.cpp index daa2ca366f..eb94a1bc2e 100644 --- a/src/order_cmd.cpp +++ b/src/order_cmd.cpp @@ -182,6 +182,7 @@ static TileIndex GetOrderLocation(const Order& o) /** Add an order to the orderlist of a vehicle. * @param tile unused + * @param flags operation to perform * @param p1 various bitstuffed elements * - p1 = (bit 0 - 15) - ID of the vehicle * - p1 = (bit 16 - 31) - the selected order (if any). If the last order is given, @@ -478,6 +479,7 @@ static void RemoveSharedOrderVehicleList(Vehicle *v) /** Delete an order from the orderlist of a vehicle. * @param tile unused + * @param flags operation to perform * @param p1 the ID of the vehicle * @param p2 the order to delete (max 255) */ @@ -557,6 +559,7 @@ int32 CmdDeleteOrder(TileIndex tile, uint32 flags, uint32 p1, uint32 p2) /** Goto next order of order-list. * @param tile unused + * @param flags operation to perform * @param p1 The ID of the vehicle which order is skipped * @param p2 unused */ @@ -600,6 +603,7 @@ int32 CmdSkipOrder(TileIndex tile, uint32 flags, uint32 p1, uint32 p2) /** Modify an order in the orderlist of a vehicle. * @param tile unused + * @param flags operation to perform * @param p1 various bitstuffed elements * - p1 = (bit 0 - 15) - ID of the vehicle * - p1 = (bit 16 - 31) - the selected order (if any). If the last order is given, @@ -680,6 +684,8 @@ int32 CmdModifyOrder(TileIndex tile, uint32 flags, uint32 p1, uint32 p2) } /** Clone/share/copy an order-list of an other vehicle. + * @param tile unused + * @param flags operation to perform * @param p1 various bitstuffed elements * - p1 = (bit 0-15) - destination vehicle to clone orders to (p1 & 0xFFFF) * - p1 = (bit 16-31) - source vehicle to clone orders from, if any (none for CO_UNSHARE) @@ -812,6 +818,7 @@ int32 CmdCloneOrder(TileIndex tile, uint32 flags, uint32 p1, uint32 p2) /** Add/remove refit orders from an order * @param tile Not used + * @param flags operation to perform * @param p1 VehicleIndex of the vehicle having the order * @param p2 bitmask * - bit 0-7 CargoID @@ -937,6 +944,7 @@ void RestoreVehicleOrders(const Vehicle* v, const BackuppedOrders* bak) /** Restore the current order-index of a vehicle and sets service-interval. * @param tile unused + * @param flags operation to perform * @param p1 the ID of the vehicle * @param p2 various bistuffed elements * - p2 = (bit 0-15) - current order-index (p2 & 0xFFFF) diff --git a/src/spritecache.cpp b/src/spritecache.cpp index 596f316583..431df4f9ad 100644 --- a/src/spritecache.cpp +++ b/src/spritecache.cpp @@ -1,6 +1,6 @@ /* $Id$ */ -/** @file spritechache.cpp */ +/** @file spritecache.cpp */ #include "stdafx.h" #include "openttd.h" diff --git a/src/stdafx.h b/src/stdafx.h index b087f90163..ba473d4c33 100644 --- a/src/stdafx.h +++ b/src/stdafx.h @@ -1,6 +1,6 @@ /* $Id$ */ -/** @file stdfax.h */ +/** @file stdafx.h */ #ifndef STDAFX_H #define STDAFX_H diff --git a/src/widget.cpp b/src/widget.cpp index d0244a1842..cd0c68adf7 100644 --- a/src/widget.cpp +++ b/src/widget.cpp @@ -36,17 +36,13 @@ static Point HandleScrollbarHittest(const Scrollbar *sb, int top, int bottom) return pt; } -/***************************************************** - * Special handling for the scrollbar widget type. +/** Special handling for the scrollbar widget type. * Handles the special scrolling buttons and other * scrolling. - * Parameters: - * w - Window. - * wi - Pointer to the scrollbar widget. - * x - The X coordinate of the mouse click. - * y - The Y coordinate of the mouse click. - */ - + * @param w Window on which a scroll was performed. + * @param wi Pointer to the scrollbar widget. + * @param x The X coordinate of the mouse click. + * @param y The Y coordinate of the mouse click. */ void ScrollbarClickHandler(Window *w, const Widget *wi, int x, int y) { int mi, ma, pos; @@ -128,8 +124,8 @@ void ScrollbarClickHandler(Window *w, const Widget *wi, int x, int y) /** Returns the index for the widget located at the given position * relative to the window. It includes all widget-corner pixels as well. * @param *w Window to look inside - * @param x - * @param y Window client coordinates + * @param x The Window client X coordinate + * @param y The Window client y coordinate * @return A widget index, or -1 if no widget was found. */ int GetWidgetFromPos(const Window *w, int x, int y) @@ -737,7 +733,7 @@ static void ResizeWidgets(Window *w, byte a, byte b, byte c) /** Evenly distribute some widgets when resizing horizontally (often a button row) * When only two arguments are given, the widgets are presumed to be on a line and only the ends are given - * @param w widow to modify + * @param w Window to modify * @param left The leftmost widget to resize * @param right The rightmost widget to resize. Since right side of it is used, remember to set it to RESIZE_RIGHT */ diff --git a/src/window.cpp b/src/window.cpp index 3f8af69416..7eaf55d45b 100644 --- a/src/window.cpp +++ b/src/window.cpp @@ -1080,7 +1080,7 @@ static bool HandleMouseOver() * Both the areas of the old window and the new sized window are set dirty * ensuring proper redrawal. * @param w Window to resize - * @param x delta x-size of changed window (positive if larger, etc.( + * @param x delta x-size of changed window (positive if larger, etc.) * @param y delta y-size of changed window */ void ResizeWindow(Window *w, int x, int y) {