(svn r9662) -Documentation: Doxygen corrections and @file omissions

31 files changed, 122 insertions, 80 deletions

diff --git a/src/engine.cpp b/src/engine.cpp
index 862c0b10d..4a0b27161 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 192d7399a..4aed67994 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 3ba326dfc..73e2b3ad5 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 55817304b..b78f14ea5 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 f00ee5361..30b305d63 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.<br/>
+ * 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 c898003a6..4caf7927f 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 e23e8bddd..807591171 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 e8eff1c8c..7f8e42329 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 b5ca6ddd1..0c684aac2 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 3412f3bbc..08516d2ea 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 7b72a25af..78ebdc47f 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 1a20f3ac2..97bd01160 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 e63e47fb5..0d6a925b8 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 10e9a7ac4..71f7ff03f 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 48b177f3c..ee4ea14ca 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 c6b52e50a..fad44114d 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<Titem, Thash_bits> - simple hash table
+/** class CHashTableT<Titem, Thash_bits> - 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 59824a1ac..a4be0588b 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 9bc7ab1c9..c22043913 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 be8535d89..0cf500a50 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 3846878cd..f0538c678 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 <dmusicf.h>
 
 
-// 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 c7edcdade..235b28ae1 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 74c4ba525..6b5807496 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 6fd836631..a75107f66 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 eb9757f16..3212a75e2 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 8f4457791..0c5208cff 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 a94461180..0bfb21b4c 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.<br/>
- * 1.  0 -  7 display_mode, any of the NewsMode enums (NM_)<br/>
- * 2.  8 - 15 news flags, any of the NewsFlags enums (NF_) NF_INCOLOR are set automatically if needed<br/>
- * 3. 16 - 23 news category, any of the NewsType enums (NT_)<br/>
- * 4. 24 - 31 news callback function, any of the NewsCallback enums (DNC_)<br/>
+ * @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.<br/>
+ * stringid has a special meaning.
  * DNC_TRAINAVAIL, DNC_ROADAVAIL, DNC_SHIPAVAIL, DNC_AIRCRAFTAVAIL: StringID is
- * the index of the engine that is shown<br/>
+ * 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_)<br/>
+ * 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 daa2ca366..eb94a1bc2 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 596f31658..431df4f9a 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 b087f9016..ba473d4c3 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 d0244a184..cd0c68adf 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 3f8af6941..7eaf55d45 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)
 {