Mercurial > hg > openttd

changeset 6117:6def6ecb1bf7 draft

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
(svn r8853) -Cleanup: doxygen changes. Correct forgotten c files to cpp files with the @file tag as well as a few general comments style
author belugas <belugas@openttd.org>
date Fri, 23 Feb 2007 01:48:53 +0000
parents 05018fddac7b
children 19b21ef194e1
files src/aircraft.h src/aircraft_cmd.cpp src/aircraft_gui.cpp src/airport.cpp src/airport.h src/airport_gui.cpp src/airport_movement.h src/autoreplace_gui.cpp src/aystar.cpp src/aystar.h src/bridge_gui.cpp src/disaster_cmd.cpp src/elrail.cpp src/fios.cpp src/music/qtmidi.cpp src/newgrf_station.cpp src/players.cpp src/rail_gui.cpp src/saveload.cpp src/station.cpp src/station_cmd.cpp src/tunnelbridge_cmd.cpp src/viewport.cpp src/win32.cpp src/win32.h src/window.cpp src/window.h
diffstat 27 files changed, 211 insertions(+), 185 deletions(-) [+]
line wrap: on
line diff
--- a/src/aircraft.h
+++ b/src/aircraft.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file aircraft_cmd.h */
+
 #ifndef AIRCRAFT_H
 #define AIRCRAFT_H
 
--- a/src/aircraft_cmd.cpp
+++ b/src/aircraft_cmd.cpp
@@ -1,5 +1,8 @@
 /* $Id$ */
 
+/** @file aircraft_cmd.cpp
+ * This file deals with aircraft and airport movements functionalities */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "aircraft.h"
--- a/src/aircraft_gui.cpp
+++ b/src/aircraft_gui.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file aircraft_gui.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "aircraft.h"
--- a/src/airport.cpp
+++ b/src/airport.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file airport.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "debug.h"
--- a/src/airport.h
+++ b/src/airport.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file airport.h Various declarations for airports */
+
 #ifndef AIRPORT_H
 #define AIRPORT_H
 
--- a/src/airport_gui.cpp
+++ b/src/airport_gui.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file airport_gui.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "table/sprites.h"
--- a/src/airport_movement.h
+++ b/src/airport_movement.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file airport_movement.h Heart of the airports and their finite state machines */
+
 #ifndef AIRPORT_MOVEMENT_H
 #define AIRPORT_MOVEMENT_H
 
--- a/src/autoreplace_gui.cpp
+++ b/src/autoreplace_gui.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file autoreplace_gui.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "debug.h"
--- a/src/aystar.cpp
+++ b/src/aystar.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file aystar.cpp
+
 /*
  * This file has the core function for AyStar
  *  AyStar is a fast pathfinding routine and is used for things like
--- a/src/aystar.h
+++ b/src/aystar.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/*
+/** @file aystar.h
  * This file has the header for AyStar
  *  AyStar is a fast pathfinding routine and is used for things like
  *  AI_pathfinding and Train_pathfinding.
--- a/src/bridge_gui.cpp
+++ b/src/bridge_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file bridge_gui.c Graphical user interface for bridge construction*/
+/** @file bridge_gui.cpp Graphical user interface for bridge construction */
 
 #include "stdafx.h"
 #include "openttd.h"
--- a/src/disaster_cmd.cpp
+++ b/src/disaster_cmd.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file
+/** @file disaster_cmd.cpp
  * All disaster/easter egg vehicles are handled here.
  * The general flow of control for the disaster vehicles is as follows:
  * <ol>
--- a/src/elrail.cpp
+++ b/src/elrail.cpp
@@ -1,5 +1,5 @@
 /* $Id$ */
-/** @file elrail.c
+/** @file elrail.cpp
  * This file deals with displaying wires and pylons for electric railways.
  * <h2>Basics</h2>
  *
--- a/src/fios.cpp
+++ b/src/fios.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file fios.c
+/** @file fios.cpp
  * This file contains functions for building file lists for the save/load dialogs.
  */
 
--- a/src/music/qtmidi.cpp
+++ b/src/music/qtmidi.cpp
@@ -1,7 +1,7 @@
 /* $Id$ */
 
 /**
- * @file qtmidi.c
+ * @file qtmidi.cpp
  * @brief MIDI music player for MacOS X using QuickTime.
  *
  * This music player should work in all MacOS X releases starting from 10.0,
--- a/src/newgrf_station.cpp
+++ b/src/newgrf_station.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file newgrf_station.c Functions for dealing with station classes and custom stations. */
+/** @file newgrf_station.cpp Functions for dealing with station classes and custom stations. */
 
 #include "stdafx.h"
 #include "openttd.h"
--- a/src/players.cpp
+++ b/src/players.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file players.c
+/** @file players.cpp
  * @todo Cleanup the messy DrawPlayerFace function asap
  */
 #include "stdafx.h"
--- a/src/rail_gui.cpp
+++ b/src/rail_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file rail_gui.c File for dealing with rail construction user interface */
+/** @file rail_gui.cpp File for dealing with rail construction user interface */
 
 #include "stdafx.h"
 #include "openttd.h"
--- a/src/saveload.cpp
+++ b/src/saveload.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file
+/** @file saveload.cpp
  * All actions handling saving and loading goes on in this file. The general actions
  * are as follows for saving a game (loading is analogous):
  * <ol>
@@ -12,8 +12,6 @@
  * <li>when the buffer is full; flush it to the output (eg save to file) (_sl.buf, _sl.bufp, _sl.bufe)
  * <li>repeat this until everything is done, and flush any remaining output to file
  * </ol>
- * @see ChunkHandler
- * @see SaveLoad
  */
 #include "stdafx.h"
 #include "openttd.h"
@@ -31,43 +29,43 @@
 #include <setjmp.h>
 
 extern const uint16 SAVEGAME_VERSION = 47;
-uint16 _sl_version;       /// the major savegame version identifier
-byte   _sl_minor_version; /// the minor savegame version, DO NOT USE!
+uint16 _sl_version;       ///< the major savegame version identifier
+byte   _sl_minor_version; ///< the minor savegame version, DO NOT USE!
 
 typedef void WriterProc(uint len);
 typedef uint ReaderProc(void);
 
 /** The saveload struct, containing reader-writer functions, bufffer, version, etc. */
 static struct {
-	bool save;                           /// are we doing a save or a load atm. True when saving
-	byte need_length;                    /// ???
-	byte block_mode;                     /// ???
-	bool error;                          /// did an error occur or not
+	bool save;                           ///< are we doing a save or a load atm. True when saving
+	byte need_length;                    ///< ???
+	byte block_mode;                     ///< ???
+	bool error;                          ///< did an error occur or not
 
-	int obj_len;                         /// the length of the current object we are busy with
-	int array_index, last_array_index;   /// in the case of an array, the current and last positions
+	int obj_len;                         ///< the length of the current object we are busy with
+	int array_index, last_array_index;   ///< in the case of an array, the current and last positions
 
-	uint32 offs_base;                    /// the offset in number of bytes since we started writing data (eg uncompressed savegame size)
+	uint32 offs_base;                    ///< the offset in number of bytes since we started writing data (eg uncompressed savegame size)
 
-	WriterProc *write_bytes;             /// savegame writer function
-	ReaderProc *read_bytes;              /// savegame loader function
+	WriterProc *write_bytes;             ///< savegame writer function
+	ReaderProc *read_bytes;              ///< savegame loader function
 
-	const ChunkHandler* const *chs;      /// the chunk of data that is being processed atm (vehicles, signs, etc.)
-	const SaveLoad* const *includes;     /// the internal layouf of the given chunk
+	const ChunkHandler* const *chs;      ///< the chunk of data that is being processed atm (vehicles, signs, etc.)
+	const SaveLoad* const *includes;     ///< the internal layouf of the given chunk
 
-	/** When saving/loading savegames, they are always saved to a temporary memory-place
+	/* When saving/loading savegames, they are always saved to a temporary memory-place
 	 * to be flushed to file (save) or to final place (load) when full. */
-	byte *bufp, *bufe;                   /// bufp(ointer) gives the current position in the buffer bufe(nd) gives the end of the buffer
+	byte *bufp, *bufe;                   ///< bufp(ointer) gives the current position in the buffer bufe(nd) gives the end of the buffer
 
-	// these 3 may be used by compressor/decompressors.
-	byte *buf;                           /// pointer to temporary memory to read/write, initialized by SaveLoadFormat->initread/write
-	byte *buf_ori;                       /// pointer to the original memory location of buf, used to free it afterwards
-	uint bufsize;                        /// the size of the temporary memory *buf
-	FILE *fh;                            /// the file from which is read or written to
+	/* these 3 may be used by compressor/decompressors. */
+	byte *buf;                           ///< pointer to temporary memory to read/write, initialized by SaveLoadFormat->initread/write
+	byte *buf_ori;                       ///< pointer to the original memory location of buf, used to free it afterwards
+	uint bufsize;                        ///< the size of the temporary memory *buf
+	FILE *fh;                            ///< the file from which is read or written to
 
-	void (*excpt_uninit)(void);          /// the function to execute on any encountered error
-	const char *excpt_msg;               /// the error message
-	jmp_buf excpt;                       /// @todo used to jump to "exception handler";  really ugly
+	void (*excpt_uninit)(void);          ///< the function to execute on any encountered error
+	const char *excpt_msg;               ///< the error message
+	jmp_buf excpt;                       ///< @todo used to jump to "exception handler";  really ugly
 } _sl;
 
 
@@ -89,8 +87,8 @@
 static inline uint32 SlGetOffs(void) {return _sl.offs_base - (_sl.bufe - _sl.bufp);}
 
 /** Return the size in bytes of a certain type of normal/atomic variable
- * as it appears in memory. @see VarTypes
- * @param conv @VarType type of variable that is used for calculating the size
+ * as it appears in memory. See VarTypes
+ * @param conv VarType type of variable that is used for calculating the size
  * @return Return the size of this type in bytes */
 static inline byte SlCalcConvMemLen(VarType conv)
 {
@@ -101,8 +99,8 @@
 }
 
 /** Return the size in bytes of a certain type of normal/atomic variable
- * as it appears in a saved game. @see VarTypes
- * @param conv @VarType type of variable that is used for calculating the size
+ * as it appears in a saved game. See VarTypes
+ * @param conv VarType type of variable that is used for calculating the size
  * @return Return the size of this type in bytes */
 static inline byte SlCalcConvFileLen(VarType conv)
 {
@@ -112,7 +110,7 @@
 	return conv_file_size[length];
 }
 
-/* Return the size in bytes of a reference (pointer) */
+/** Return the size in bytes of a reference (pointer) */
 static inline size_t SlCalcRefLen(void) {return 2;}
 
 /** Flush the output buffer by writing to disk with the given reader.
@@ -121,7 +119,7 @@
  */
 static void SlWriteFill(void)
 {
-	// flush the buffer to disk (the writer)
+	/* flush the buffer to disk (the writer) */
 	if (_sl.bufp != NULL) {
 		uint len = _sl.bufp - _sl.buf;
 		_sl.offs_base += len;
@@ -129,7 +127,7 @@
 	}
 
 	/* All the data from the buffer has been written away, rewind to the beginning
-	* to start reading in more data */
+	 * to start reading in more data */
 	_sl.bufp = _sl.buf;
 	_sl.bufe = _sl.buf + _sl.bufsize;
 }
@@ -333,9 +331,9 @@
 		_sl.need_length = NL_NONE;
 		switch (_sl.block_mode) {
 		case CH_RIFF:
-			// Ugly encoding of >16M RIFF chunks
-			// The lower 24 bits are normal
-			// The uppermost 4 bits are bits 24:27
+			/* Ugly encoding of >16M RIFF chunks
+			 * The lower 24 bits are normal
+			 * The uppermost 4 bits are bits 24:27 */
 			assert(length < (1<<28));
 			SlWriteUint32((length & 0xFFFFFF) | ((length >> 24) << 28));
 			break;
@@ -439,13 +437,13 @@
  * and then write them to file, endian safely. Loading a value
  * goes exactly the opposite way
  * @param ptr The object being filled/read
- * @param conv @VarType type of the current element of the struct
+ * @param conv VarType type of the current element of the struct
  */
 static void SlSaveLoadConv(void *ptr, VarType conv)
 {
 	int64 x = 0;
 
-	if (_sl.save) { /* SAVE values */
+	if (_sl.save) { // SAVE values
 		/* Read a value from the struct. These ARE endian safe. */
 		x = ReadValue(ptr, conv);
 
@@ -462,7 +460,7 @@
 		case SLE_FILE_U64:                                   SlWriteUint64(x);break;
 		default: NOT_REACHED();
 		}
-	} else { /* LOAD values */
+	} else { // LOAD values
 
 		/* Read a value from the file */
 		switch (GetVarFileType(conv)) {
@@ -533,7 +531,7 @@
 {
 	size_t len;
 
-	if (_sl.save) { /* SAVE string */
+	if (_sl.save) { // SAVE string
 		switch (GetVarMemType(conv)) {
 			default: NOT_REACHED();
 			case SLE_VAR_STRB:
@@ -549,7 +547,7 @@
 
 		SlWriteArrayLength(len);
 		SlCopyBytes(ptr, len);
-	} else { /* LOAD string */
+	} else { // LOAD string
 		len = SlReadArrayLength();
 
 		switch (GetVarMemType(conv)) {
@@ -566,7 +564,7 @@
 				}
 				break;
 			case SLE_VAR_STR:
-			case SLE_VAR_STRQ: /* Malloc'd string, free previous incarnation, and allocate */
+			case SLE_VAR_STRQ: // Malloc'd string, free previous incarnation, and allocate
 				free(*(char**)ptr);
 				*(char**)ptr = (char*)malloc(len + 1); // terminating '\0'
 				ptr = *(char**)ptr;
@@ -581,7 +579,7 @@
 /**
  * Return the size in bytes of a certain type of atomic array
  * @param length The length of the array counted in elements
- * @param conv @VarType type of the variable that is used in calculating the size
+ * @param conv VarType type of the variable that is used in calculating the size
  */
 static inline size_t SlCalcArrayLen(uint length, VarType conv)
 {
@@ -592,14 +590,14 @@
  * Save/Load an array.
  * @param array The array being manipulated
  * @param length The length of the array in elements
- * @param conv @VarType type of the atomic array (int, byte, uint64, etc.)
+ * @param conv VarType type of the atomic array (int, byte, uint64, etc.)
  */
 void SlArray(void *array, uint length, VarType conv)
 {
-	// Automatically calculate the length?
+	/* Automatically calculate the length? */
 	if (_sl.need_length != NL_NONE) {
 		SlSetLength(SlCalcArrayLen(length, conv));
-		// Determine length only?
+		/* Determine length only? */
 		if (_sl.need_length == NL_CALCLENGTH) return;
 	}
 
@@ -628,7 +626,7 @@
 	}
 }
 
-/* Are we going to save this object or not? */
+/** Are we going to save this object or not? */
 static inline bool SlIsObjectValidInSavegame(const SaveLoad *sld)
 {
 	if (_sl_version < sld->version_from || _sl_version > sld->version_to) return false;
@@ -652,13 +650,13 @@
 
 /**
  * Calculate the size of an object.
- * @param sld The @SaveLoad description of the object so we know how to manipulate it
+ * @param sld The SaveLoad description of the object so we know how to manipulate it
  */
 static size_t SlCalcObjLength(const void *object, const SaveLoad *sld)
 {
 	size_t length = 0;
 
-	// Need to determine the length and write a length tag.
+	/* Need to determine the length and write a length tag. */
 	for (; sld->cmd != SL_END; sld++) {
 		length += SlCalcObjMemberLength(object, sld);
 	}
@@ -711,8 +709,8 @@
 
 		switch (sld->cmd) {
 		case SL_VAR: SlSaveLoadConv(ptr, conv); break;
-		case SL_REF: /* Reference variable, translate */
-			/// @todo XXX - another artificial limitof 65K elements of pointers?
+		case SL_REF: // Reference variable, translate
+			/* @todo XXX - another artificial limitof 65K elements of pointers? */
 			if (_sl.save) { // XXX - read/write pointer as uint16? What is with higher indeces?
 				SlWriteUint16(ReferenceToInt(*(void**)ptr, (SLRefType)conv));
 			} else {
@@ -726,10 +724,10 @@
 		break;
 
 	/* SL_WRITEBYTE translates a value of a variable to another one upon
-   * saving or loading.
-   * XXX - variable renaming abuse
-   * game_value: the value of the variable ingame is abused by sld->version_from
-   * file_value: the value of the variable in the savegame is abused by sld->version_to */
+	 * saving or loading.
+	 * XXX - variable renaming abuse
+	 * game_value: the value of the variable ingame is abused by sld->version_from
+	 * file_value: the value of the variable in the savegame is abused by sld->version_to */
 	case SL_WRITEBYTE:
 		if (_sl.save) {
 			SlWriteByte(sld->version_to);
@@ -752,11 +750,11 @@
 /**
  * Main SaveLoad function.
  * @param object The object that is being saved or loaded
- * @param sld The @SaveLoad description of the object so we know how to manipulate it
+ * @param sld The SaveLoad description of the object so we know how to manipulate it
  */
 void SlObject(void *object, const SaveLoad *sld)
 {
-	// Automatically calculate the length?
+	/* Automatically calculate the length? */
 	if (_sl.need_length != NL_NONE) {
 		SlSetLength(SlCalcObjLength(object, sld));
 		if (_sl.need_length == NL_CALCLENGTH) return;
@@ -795,18 +793,18 @@
 
 	assert(_sl.save);
 
-	// Tell it to calculate the length
+	/* Tell it to calculate the length */
 	_sl.need_length = NL_CALCLENGTH;
 	_sl.obj_len = 0;
 	proc(arg);
 
-	// Setup length
+	/* Setup length */
 	_sl.need_length = NL_WANTLENGTH;
 	SlSetLength(_sl.obj_len);
 
 	offs = SlGetOffs() + _sl.obj_len;
 
-	// And write the stuff
+	/* And write the stuff */
 	proc(arg);
 
 	assert(offs == SlGetOffs());
@@ -835,7 +833,7 @@
 		break;
 	default:
 		if ((m & 0xF) == CH_RIFF) {
-			// Read length
+			/* Read length */
 			len = (SlReadByte() << 16) | ((m >> 4) << 24);
 			len += SlReadUint16();
 			_sl.obj_len = len;
@@ -866,7 +864,7 @@
 	DEBUG(sl, 2, "Saving chunk %c%c%c%c", ch->id >> 24, ch->id >> 16, ch->id >> 8, ch->id);
 
 	if (ch->flags & CH_AUTO_LENGTH) {
-		// Need to calculate the length. Solve that by calling SlAutoLength in the save_proc.
+		/* Need to calculate the length. Solve that by calling SlAutoLength in the save_proc. */
 		_tmp_proc_1 = proc;
 		proc = SlStubSaveProc;
 	}
@@ -911,7 +909,7 @@
 		}
 	}
 
-	// Terminator
+	/* Terminator */
 	SlWriteUint32(0);
 }
 
@@ -949,9 +947,9 @@
 	}
 }
 
-//*******************************************
-//********** START OF LZO CODE **************
-//*******************************************
+/*******************************************
+ ********** START OF LZO CODE **************
+ *******************************************/
 #define LZO_SIZE 8192
 
 #include "minilzo.h"
@@ -963,10 +961,10 @@
 	uint32 size;
 	uint len;
 
-	// Read header
+	/* Read header*/
 	if (fread(tmp, sizeof(tmp), 1, _sl.fh) != 1) SlError("file read failed");
 
-	// Check if size is bad
+	/* Check if size is bad */
 	((uint32*)out)[0] = size = tmp[1];
 
 	if (_sl_version != 0) {
@@ -976,19 +974,19 @@
 
 	if (size >= sizeof(out)) SlError("inconsistent size");
 
-	// Read block
+	/* Read block */
 	if (fread(out + sizeof(uint32), size, 1, _sl.fh) != 1) SlError("file read failed");
 
-	// Verify checksum
+	/* Verify checksum */
 	if (tmp[0] != lzo_adler32(0, out, size + sizeof(uint32))) SlError("bad checksum");
 
-	// Decompress
+	/* Decompress */
 	lzo1x_decompress(out + sizeof(uint32)*1, size, _sl.buf, &len, NULL);
 	return len;
 }
 
-// p contains the pointer to the buffer, len contains the pointer to the length.
-// len bytes will be written, p and l will be updated to reflect the next buffer.
+/* p contains the pointer to the buffer, len contains the pointer to the length.
+ * len bytes will be written, p and l will be updated to reflect the next buffer. */
 static void WriteLZO(uint size)
 {
 	byte out[LZO_SIZE + LZO_SIZE / 64 + 16 + 3 + 8];
@@ -1013,9 +1011,9 @@
 	free(_sl.buf_ori);
 }
 
-//*********************************************
-//******** START OF NOCOMP CODE (uncompressed)*
-//*********************************************
+/*********************************************
+ ******** START OF NOCOMP CODE (uncompressed)*
+ *********************************************/
 static uint ReadNoComp(void)
 {
 	return fread(_sl.buf, 1, LZO_SIZE, _sl.fh);
@@ -1038,9 +1036,9 @@
 	free(_sl.buf_ori);
 }
 
-//********************************************
-//********** START OF MEMORY CODE (in ram)****
-//********************************************
+/********************************************
+ ********** START OF MEMORY CODE (in ram)****
+ ********************************************/
 
 #include "table/strings.h"
 #include "table/sprites.h"
@@ -1084,9 +1082,9 @@
 	_sl.buf = GetSavegame(_ts.count);
 }
 
-//********************************************
-//********** START OF ZLIB CODE **************
-//********************************************
+/********************************************
+ ********** START OF ZLIB CODE **************
+ ********************************************/
 
 #if defined(WITH_ZLIB)
 #include <zlib.h>
@@ -1111,12 +1109,12 @@
 	_z.avail_out = 4096;
 
 	do {
-		// read more bytes from the file?
+		/* read more bytes from the file?*/
 		if (_z.avail_in == 0) {
 			_z.avail_in = fread(_z.next_in = _sl.buf + 4096, 1, 4096, _sl.fh);
 		}
 
-		// inflate the data
+		/* inflate the data */
 		r = inflate(&_z, 0);
 		if (r == Z_STREAM_END)
 			break;
@@ -1155,7 +1153,7 @@
 		z->next_out = buf;
 		z->avail_out = sizeof(buf);
 		r = deflate(z, mode);
-			// bytes were emitted?
+			/* bytes were emitted? */
 		if ((n=sizeof(buf) - z->avail_out) != 0) {
 			if (fwrite(buf, n, 1, _sl.fh) != 1) SlError("file write error");
 		}
@@ -1172,7 +1170,7 @@
 
 static void UninitWriteZlib(void)
 {
-	// flush any pending output.
+	/* flush any pending output. */
 	if (_sl.fh) WriteZlibLoop(&_z, NULL, 0, Z_FINISH);
 	deflateEnd(&_z);
 	free(_sl.buf_ori);
@@ -1180,11 +1178,11 @@
 
 #endif /* WITH_ZLIB */
 
-//*******************************************
-//************* END OF CODE *****************
-//*******************************************
+/*******************************************
+ ************* END OF CODE *****************
+ *******************************************/
 
-// these define the chunks
+/* these define the chunks */
 extern const ChunkHandler _misc_chunk_handlers[];
 extern const ChunkHandler _setting_chunk_handlers[];
 extern const ChunkHandler _player_chunk_handlers[];
@@ -1220,7 +1218,7 @@
 	NULL,
 };
 
-// used to include a vehicle desc in another desc.
+/* used to include a vehicle desc in another desc. */s
 extern const SaveLoad _common_veh_desc[];
 static const SaveLoad* const _desc_includes[] = {
 	_common_veh_desc
@@ -1233,7 +1231,7 @@
  * Remember that a NULL item has value 0, and all
  * indeces have +1, so vehicle 0 is saved as index 1.
  * @param obj The object that we want to get the index of
- * @param rt @SLRefType type of the object the index is being sought of
+ * @param rt SLRefType type of the object the index is being sought of
  * @return Return the pointer converted to an index of the type pointed to
  */
 static uint ReferenceToInt(const void *obj, SLRefType rt)
@@ -1261,7 +1259,7 @@
  * Remember that an index of 0 is a NULL pointer so all indeces
  * are +1 so vehicle 0 is saved as 1.
  * @param index The index that is being converted to a pointer
- * @param rt @SLRefType type of the object the pointer is sought of
+ * @param rt SLRefType type of the object the pointer is sought of
  * @return Return the index converted to a pointer of any type
  */
 static void *IntToReference(uint index, SLRefType rt)
@@ -1329,16 +1327,16 @@
 
 /** The format for a reader/writer type of a savegame */
 typedef struct {
-	const char *name;           /// name of the compressor/decompressor (debug-only)
-	uint32 tag;                 /// the 4-letter tag by which it is identified in the savegame
+	const char *name;           ///< name of the compressor/decompressor (debug-only)
+	uint32 tag;                 ///< the 4-letter tag by which it is identified in the savegame
 
-	bool (*init_read)(void);    /// function executed upon initalization of the loader
-	ReaderProc *reader;         /// function that loads the data from the file
-	void (*uninit_read)(void);  /// function executed when reading is finished
+	bool (*init_read)(void);    ///< function executed upon initalization of the loader
+	ReaderProc *reader;         ///< function that loads the data from the file
+	void (*uninit_read)(void);  ///< function executed when reading is finished
 
-	bool (*init_write)(void);   /// function executed upon intialization of the saver
-	WriterProc *writer;         /// function that saves the data to the file
-	void (*uninit_write)(void); /// function executed when writing is done
+	bool (*init_write)(void);   ///< function executed upon intialization of the saver
+	WriterProc *writer;         ///< function that saves the data to the file
+	void (*uninit_write)(void); ///< function executed when writing is done
 } SaveLoadFormat;
 
 static const SaveLoadFormat _saveload_formats[] = {
@@ -1356,13 +1354,13 @@
  * Return the savegameformat of the game. Whether it was create with ZLIB compression
  * uncompressed, or another type
  * @param s Name of the savegame format. If NULL it picks the first available one
- * @return Pointer to @SaveLoadFormat struct giving all characteristics of this type of savegame
+ * @return Pointer to SaveLoadFormat struct giving all characteristics of this type of savegame
  */
 static const SaveLoadFormat *GetSavegameFormat(const char *s)
 {
 	const SaveLoadFormat *def = endof(_saveload_formats) - 1;
 
-	// find default savegame format, the highest one with which files can be written
+	/* find default savegame format, the highest one with which files can be written */
 	while (!def->init_write) def--;
 
 	if (s != NULL && s[0] != '\0') {
@@ -1377,7 +1375,7 @@
 	return def;
 }
 
-// actual loader/saver function
+/* actual loader/saver function */
 void InitializeGame(int mode, uint size_x, uint size_y);
 extern bool AfterLoadGame(void);
 extern void BeforeSaveGame(void);
@@ -1509,7 +1507,7 @@
 
 	/* An instance of saving is already active, so don't go saving again */
 	if (_ts.saveinprogress && mode == SL_SAVE) {
-		// if not an autosave, but a user action, show error message
+		/* if not an autosave, but a user action, show error message */
 		if (!_do_autosave) ShowErrorMessage(INVALID_STRING_ID, STR_SAVE_STILL_IN_PROGRESS, 0, 0);
 		return SL_OK;
 	}
@@ -1541,7 +1539,7 @@
 	if (setjmp(_sl.excpt)) {
 		AbortSaveLoad();
 
-		// deinitialize compressor.
+		/* deinitialize compressor. */
 		_sl.excpt_uninit();
 
 		/* A saver/loader exception!! reinitialize all variables to prevent crash! */
@@ -1590,7 +1588,7 @@
 			return AbortSaveLoad();
 		}
 
-		// see if we have any loader for this type.
+		/* see if we have any loader for this type. */
 		for (fmt = _saveload_formats; ; fmt++) {
 			/* No loader found, treat as version 0 and use LZO format */
 			if (fmt == endof(_saveload_formats)) {
@@ -1609,12 +1607,12 @@
 			}
 
 			if (fmt->tag == hdr[0]) {
-				// check version number
+				/* check version number */
 				_sl_version = TO_BE32(hdr[1]) >> 16;
 				/* Minor is not used anymore from version 18.0, but it is still needed
-				 *  in versions before that (4 cases) which can't be removed easy.
-				 *  Therefor it is loaded, but never saved (or, it saves a 0 in any scenario).
-				 *  So never EVER use this minor version again. -- TrueLight -- 22-11-2005 */
+				 * in versions before that (4 cases) which can't be removed easy.
+				 * Therefor it is loaded, but never saved (or, it saves a 0 in any scenario).
+				 * So never EVER use this minor version again. -- TrueLight -- 22-11-2005 */
 				_sl_minor_version = (TO_BE32(hdr[1]) >> 8) & 0xFF;
 
 				DEBUG(sl, 1, "Loading savegame version %d", _sl_version);
@@ -1631,7 +1629,7 @@
 		_sl.read_bytes = fmt->reader;
 		_sl.excpt_uninit = fmt->uninit_read;
 
-		// loader for this savegame type is not implemented?
+		/* loader for this savegame type is not implemented? */
 		if (fmt->init_read == NULL) {
 			ShowInfoF("Loader for '%s' is not available.", fmt->name);
 			return AbortSaveLoad();
@@ -1686,7 +1684,7 @@
 		DEBUG(sl, 0, "Savegame is obsolete or invalid format");
 		mode = SL_LOAD; // don't try to get filename, just show name as it is written
 	} else {
-		// see if we have any loader for this type.
+		/* see if we have any loader for this type. */
 		for (fmt = _saveload_formats; fmt != endof(_saveload_formats); fmt++) {
 			if (fmt->tag == hdr) {
 				mode = SL_LOAD; // new type of savegame
--- a/src/station.cpp
+++ b/src/station.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file station_cmd.c */
+/** @file station_cmd.cpp */
 
 #include "stdafx.h"
 #include "openttd.h"
--- a/src/station_cmd.cpp
+++ b/src/station_cmd.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file station_cmd.c */
+/** @file station_cmd.cpp */
 
 #include "stdafx.h"
 #include "openttd.h"
--- a/src/tunnelbridge_cmd.cpp
+++ b/src/tunnelbridge_cmd.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file tunnelbridge_cmd.c
+/** @file tunnelbridge_cmd.cpp
  * This file deals with tunnels and bridges (non-gui stuff)
  * @todo seperate this file into two
  */
--- a/src/viewport.cpp
+++ b/src/viewport.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file viewport.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "debug.h"
@@ -23,7 +25,6 @@
 
 #define VIEWPORT_DRAW_MEM (65536 * 2)
 
-/* viewport.c */
 // XXX - maximum viewports is maximum windows - 2 (main toolbar + status bar)
 static ViewPort _viewports[25 - 2];
 static uint32 _active_viewports;    ///< bitmasked variable where each bit signifies if a viewport is in use or not
--- a/src/win32.cpp
+++ b/src/win32.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file win32.cpp Implementation of MS Windows system calls */
+
 #include "stdafx.h"
 #include "hal.h"
 #include "openttd.h"
--- a/src/win32.h
+++ b/src/win32.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file win32.h declarations of functions for MS windows systems */
+
 #ifndef WIN32_H
 #define WIN32_H
 
--- a/src/window.cpp
+++ b/src/window.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file window.cpp windowing system, widgets and events */
+
 #include "stdafx.h"
 #include <stdarg.h>
 #include "openttd.h"
--- a/src/window.h
+++ b/src/window.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file window.h regroups declarations for all windowing system, as well as a few helper functions */
+
 #ifndef WINDOW_H
 #define WINDOW_H
 
@@ -59,9 +61,9 @@
 	 * They are used in the same place as the above RESIZE_x flags, Widget visual_flags.
 	 * These states are used in exceptions. If nothing is specified, they will indicate
 	 * Enabled, visible or unclicked widgets*/
-	WIDG_DISABLED = 4,  // widget is greyed out, not available
-	WIDG_HIDDEN   = 5,  // widget is made invisible
-	WIDG_LOWERED  = 6,  // widget is paint lowered, a pressed button in fact
+	WIDG_DISABLED = 4,  ///< widget is greyed out, not available
+	WIDG_HIDDEN   = 5,  ///< widget is made invisible
+	WIDG_LOWERED  = 6,  ///< widget is paint lowered, a pressed button in fact
 } ResizeFlag;
 
 /* used to indicate the end of widgets' list for vararg functions */
@@ -70,8 +72,8 @@
 };
 
 typedef struct Widget {
-	byte type;                        ///< Widget type, see @WindowWidgetTypes
-	byte display_flags;               ///< Resize direction, alignment, etc. during resizing, see @ResizeFlags
+	byte type;                        ///< Widget type, see WindowWidgetTypes
+	byte display_flags;               ///< Resize direction, alignment, etc. during resizing, see ResizeFlags
 	byte color;                       ///< Widget colour, see docs/ottd-colourtext-palette.png
 	int16 left, right, top, bottom;   ///< The position offsets inside the window
 	uint16 data;                      ///< The String/Image or special code (list-matrixes) of a widget
@@ -164,23 +166,23 @@
 		} mouseover;
 
 		struct {
-			bool cont;     // continue the search? (default true)
-			uint16 key;    // 16-bit Unicode value of the key
-			uint16 keycode;// untranslated key (including shift-state)
+			bool cont;      ///< continue the search? (default true)
+			uint16 key;     ///< 16-bit Unicode value of the key
+			uint16 keycode; ///< untranslated key (including shift-state)
 		} keypress;
 
 		struct {
-			int msg;      // message to be sent
-			int wparam;   // additional message-specific information
-			int lparam;   // additional message-specific information
+			int msg;      ///< message to be sent
+			int wparam;   ///< additional message-specific information
+			int lparam;   ///< additional message-specific information
 		} message;
 
 		struct {
-			Point delta;   // delta position against position of last call
+			Point delta;   ///< delta position against position of last call
 		} scroll;
 
 		struct {
-			int wheel;     // how much was 'wheel'd'
+			int wheel;     ///< how much was 'wheel'd'
 		} wheel;
 	} we;
 };
@@ -195,14 +197,14 @@
 } WindowDesc;
 
 enum WindowDefaultFlag {
-	WDF_STD_TOOLTIPS    =   1, /* use standard routine when displaying tooltips */
-	WDF_DEF_WIDGET      =   2, /* default widget control for some widgets in the on click event */
-	WDF_STD_BTN         =   4, /* default handling for close and drag widgets (widget no 0 and 1) */
+	WDF_STD_TOOLTIPS    =   1, ///< use standard routine when displaying tooltips
+	WDF_DEF_WIDGET      =   2, ///< default widget control for some widgets in the on click event
+	WDF_STD_BTN         =   4, ///< default handling for close and drag widgets (widget no 0 and 1)
 
-	WDF_UNCLICK_BUTTONS =  16, /* Unclick buttons when the window event times out */
-	WDF_STICKY_BUTTON   =  32, /* Set window to sticky mode; they are not closed unless closed with 'X' (widget 2) */
-	WDF_RESIZABLE       =  64, /* A window can be resized */
-	WDF_MODAL           = 128, /* The window is a modal child of some other window, meaning the parent is 'inactive' */
+	WDF_UNCLICK_BUTTONS =  16, ///< Unclick buttons when the window event times out */
+	WDF_STICKY_BUTTON   =  32, ///< Set window to sticky mode; they are not closed unless closed with 'X' (widget 2)
+	WDF_RESIZABLE       =  64, ///< A window can be resized
+	WDF_MODAL           = 128, ///< The window is a modal child of some other window, meaning the parent is 'inactive'
 };
 
 /* can be used as x or y coordinates to cause a specific placement */
@@ -214,12 +216,12 @@
 };
 
 typedef struct Textbuf {
-	char *buf;                  /* buffer in which text is saved */
-	uint16 maxlength, maxwidth; /* the maximum size of the buffer. Maxwidth specifies screensize in pixels, maxlength is in bytes */
-	uint16 length, width;       /* the current size of the string. Width specifies screensize in pixels, length is in bytes */
-	bool caret;                 /* is the caret ("_") visible or not */
-	uint16 caretpos;            /* the current position of the caret in the buffer, in bytes */
-	uint16 caretxoffs;          /* the current position of the caret in pixels */
+	char *buf;                  ///< buffer in which text is saved
+	uint16 maxlength, maxwidth; ///< the maximum size of the buffer. Maxwidth specifies screensize in pixels, maxlength is in bytes
+	uint16 length, width;       ///< the current size of the string. Width specifies screensize in pixels, length is in bytes
+	bool caret;                 ///< is the caret ("_") visible or not
+	uint16 caretpos;            ///< the current position of the caret in the buffer, in bytes
+	uint16 caretxoffs;          ///< the current position of the caret in pixels
 } Textbuf;
 
 #define WP(ptr,str) (*(str*)(ptr)->custom)
@@ -233,10 +235,10 @@
 } Scrollbar;
 
 typedef struct ResizeInfo {
-	uint width; /* Minimum width and height */
+	uint width; ///< Minimum width and height
 	uint height;
 
-	uint step_width; /* In how big steps the width and height go */
+	uint step_width; ///< In how big steps the width and height go
 	uint step_height;
 } ResizeInfo;
 
@@ -281,12 +283,12 @@
 assert_compile(WINDOW_CUSTOM_SIZE >= sizeof(querystr_d));
 
 typedef struct {
-	byte item_count;      /* follow_vehicle */
-	byte sel_index;       /* scrollpos_x */
-	byte main_button;     /* scrollpos_y */
+	byte item_count;      ///< follow_vehicle
+	byte sel_index;       ///< scrollpos_x
+	byte main_button;     ///< scrollpos_y
 	byte action_id;
-	StringID string_id;   /* unk30 */
-	uint16 checked_items; /* unk32 */
+	StringID string_id;   ///< unk30
+	uint16 checked_items; ///< unk32
 	byte disabled_items;
 } menu_d;
 assert_compile(WINDOW_CUSTOM_SIZE >= sizeof(menu_d));
@@ -323,7 +325,7 @@
 		RailTypeByte railtype;
 		AirportFTAClass::Flags flags;
 	} filter;
-	byte sel_index;  // deprecated value, used for 'unified' ship and road
+	byte sel_index;  ///< deprecated value, used for 'unified' ship and road
 	bool descending_sort_order;
 	byte sort_criteria;
 	bool regenerate_list;
@@ -337,7 +339,7 @@
 	byte sel_index[2];
 	EngineID sel_engine[2];
 	uint16 count[2];
-	bool wagon_btnstate; // true means engine is selected
+	bool wagon_btnstate; ///< true means engine is selected
 	EngineList list[2];
 	bool update_left;
 	bool update_right;
@@ -397,7 +399,7 @@
 } vp_d;
 assert_compile(WINDOW_CUSTOM_SIZE >= sizeof(vp_d));
 
-// vp2_d is the same as vp_d, except for the data_# values..
+/* vp2_d is the same as vp_d, except for the data_# values.. */
 typedef struct {
 	VehicleID follow_vehicle;
 	int32 scrollpos_x;
@@ -430,24 +432,24 @@
 
 typedef enum SortListFlags {
 	VL_NONE    = 0x00,
-	VL_DESC    = 0x01,  // sort descending or ascending
-	VL_RESORT  = 0x02,  // instruct the code to resort the list in the next loop
-	VL_REBUILD = 0x04,  // create sort-listing to use for qsort and friends
+	VL_DESC    = 0x01,  ///< sort descending or ascending
+	VL_RESORT  = 0x02,  ///< instruct the code to resort the list in the next loop
+	VL_REBUILD = 0x04,  ///< create sort-listing to use for qsort and friends
 	VL_END     = 0x08
 } SortListFlags;
 
 DECLARE_ENUM_AS_BIT_SET(SortListFlags);
 
 typedef struct Listing {
-	bool order;    // Ascending/descending
-	byte criteria; // Sorting criteria
+	bool order;    ///< Ascending/descending
+	byte criteria; ///< Sorting criteria
 } Listing;
 
 typedef struct list_d {
-	uint16 list_length;  // length of the list being sorted
-	byte sort_type;      // what criteria to sort on
-	SortListFlags flags; // used to control sorting/resorting/etc.
-	uint16 resort_timer; // resort list after a given amount of ticks if set
+	uint16 list_length;  ///< length of the list being sorted
+	byte sort_type;      ///< what criteria to sort on
+	SortListFlags flags; ///< used to control sorting/resorting/etc.
+	uint16 resort_timer; ///< resort list after a given amount of ticks if set
 } list_d;
 assert_compile(WINDOW_CUSTOM_SIZE >= sizeof(list_d));
 
@@ -484,25 +486,25 @@
 enum WindowWidgetTypes {
 	WWT_EMPTY,
 
-	WWT_PANEL,      /* simple depressed panel */
-	WWT_INSET,      /* pressed (inset) panel, most commonly used as combo box _text_ area */
-	WWT_IMGBTN,     /* button with image */
-	WWT_IMGBTN_2,   /* button with diff image when clicked */
+	WWT_PANEL,      ///< simple depressed panel
+	WWT_INSET,      ///< pressed (inset) panel, most commonly used as combo box _text_ area
+	WWT_IMGBTN,     ///< button with image
+	WWT_IMGBTN_2,   ///< button with diff image when clicked
 
-	WWT_TEXTBTN,    /* button with text */
-	WWT_TEXTBTN_2,  /* button with diff text when clicked */
-	WWT_LABEL,      /* centered label */
+	WWT_TEXTBTN,    ///< button with text
+	WWT_TEXTBTN_2,  ///< button with diff text when clicked
+	WWT_LABEL,      ///< centered label
 	WWT_MATRIX,
 	WWT_SCROLLBAR,
-	WWT_FRAME,      /* frame */
+	WWT_FRAME,      ///< frame
 	WWT_CAPTION,
 
 	WWT_HSCROLLBAR,
 	WWT_STICKYBOX,
-	WWT_SCROLL2BAR, /* 2nd vertical scrollbar*/
+	WWT_SCROLL2BAR, ///< 2nd vertical scrollbar
 	WWT_RESIZEBOX,
 	WWT_CLOSEBOX,
-	WWT_LAST,       /* Last Item. use WIDGETS_END to fill up padding!! */
+	WWT_LAST,       ///< Last Item. use WIDGETS_END to fill up padding!!
 
 	WWT_MASK = 0x1F,
 
@@ -531,7 +533,7 @@
 	WF_SCROLL2           = 1 << 13,
 };
 
-/* window.c */
+/* window.cpp */
 void CallWindowEventNP(Window *w, int event);
 void CallWindowTickEvent(void);
 void SetWindowDirty(const Window *w);
@@ -724,14 +726,14 @@
 void CDECL SetWindowWidgetsHiddenState(Window *w, bool hidden_stat, int widgets, ...);
 void CDECL SetWindowWidgetsLoweredState(Window *w, bool lowered_stat, int widgets, ...);
 
-/* misc_gui.c*/
+/* misc_gui.cpp */
 void GuiShowTooltipsWithArgs(StringID str, uint paramcount, const uint params[]);
 static inline void GuiShowTooltips(StringID str)
 {
 	GuiShowTooltipsWithArgs(str, 0, NULL);
 }
 
-/* widget.c */
+/* widget.cpp */
 int GetWidgetFromPos(const Window *w, int x, int y);
 void DrawWindowWidgets(const Window *w);
 void ShowDropDownMenu(Window *w, const StringID *strings, int selected, int button, uint32 disabled_mask, uint32 hidden_mask);
@@ -745,7 +747,7 @@
 void ShowVitalWindows(void);
 Window **FindWindowZPosition(const Window *w);
 
-/* window.c */
+/* window.cpp */
 extern Window *_z_windows[];
 extern Window **_last_z_window;
 #define FOR_ALL_WINDOWS(wz) for (wz = _z_windows; wz != _last_z_window; wz++)