# HG changeset patch
# User rubidium <rubidium@openttd.org>
# Date 1210086693 0
# Node ID d48433370037ce00fabaf91503f22ca265b78658
# Parent  7895fbead8204fd7cf9dbd2cf7ece73cc81caa27
(svn r12971) -Documentation: add @file in files that missed them and add something more than whitespace as description of files that don't have a description.

diff --git a/Doxyfile b/Doxyfile
--- a/Doxyfile
+++ b/Doxyfile
@@ -76,7 +76,7 @@
 #---------------------------------------------------------------------------
 # configuration options related to the input files
 #---------------------------------------------------------------------------
-INPUT                  = ./
+INPUT                  = ./src/
 FILE_PATTERNS          = *.c \
                          *.cc \
                          *.cxx \
diff --git a/src/ai/ai.cpp b/src/ai/ai.cpp
--- a/src/ai/ai.cpp
+++ b/src/ai/ai.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file ai.cpp Base for all AIs. */
+
 #include "../stdafx.h"
 #include "../openttd.h"
 #include "../variables.h"
diff --git a/src/ai/ai.h b/src/ai/ai.h
--- a/src/ai/ai.h
+++ b/src/ai/ai.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file ai.h Base functions for all AIs. */
+
 #ifndef AI_H
 #define AI_H
 
diff --git a/src/ai/default/default.cpp b/src/ai/default/default.cpp
--- a/src/ai/default/default.cpp
+++ b/src/ai/default/default.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file default.cpp The original AI. */
+
 #include "../../stdafx.h"
 #include "../../openttd.h"
 #include "../../aircraft.h"
diff --git a/src/ai/default/default.h b/src/ai/default/default.h
--- a/src/ai/default/default.h
+++ b/src/ai/default/default.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file default.h The original AI. */
+
 #ifndef DEFAULT_H
 #define DEFAULT_H
 
diff --git a/src/ai/trolly/build.cpp b/src/ai/trolly/build.cpp
--- a/src/ai/trolly/build.cpp
+++ b/src/ai/trolly/build.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file build.cpp Building support for the trolly AI. */
+
 #include "../../stdafx.h"
 #include "../../openttd.h"
 #include "../../debug.h"
diff --git a/src/ai/trolly/pathfinder.cpp b/src/ai/trolly/pathfinder.cpp
--- a/src/ai/trolly/pathfinder.cpp
+++ b/src/ai/trolly/pathfinder.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file pathfinder.cpp Pathfinder support for the trolly AI. */
+
 #include "../../stdafx.h"
 #include "../../openttd.h"
 #include "../../bridge_map.h"
diff --git a/src/ai/trolly/shared.cpp b/src/ai/trolly/shared.cpp
--- a/src/ai/trolly/shared.cpp
+++ b/src/ai/trolly/shared.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file shared.cpp Shared functions for the trolly AI. */
+
 #include "../../stdafx.h"
 #include "../../openttd.h"
 #include "../../debug.h"
diff --git a/src/ai/trolly/trolly.cpp b/src/ai/trolly/trolly.cpp
--- a/src/ai/trolly/trolly.cpp
+++ b/src/ai/trolly/trolly.cpp
@@ -1,6 +1,8 @@
 /* $Id$ */
 
-/*
+/**
+ * @file trolly.cpp Implementation of the trolly AI.
+ *
  * This AI was created as a direct reaction to the big demand for some good AIs
  * in OTTD. Too bad it never left alpha-stage, and it is considered dead in its
  * current form.
diff --git a/src/ai/trolly/trolly.h b/src/ai/trolly/trolly.h
--- a/src/ai/trolly/trolly.h
+++ b/src/ai/trolly/trolly.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file trolly.h Functions/defines related to the trolly AI. */
+
 #ifndef AI_TROLLY_H
 #define AI_TROLLY_H
 
diff --git a/src/aircraft.h b/src/aircraft.h
--- a/src/aircraft.h
+++ b/src/aircraft.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file aircraft.h */
+/** @file aircraft.h Base for aircraft. */
 
 #ifndef AIRCRAFT_H
 #define AIRCRAFT_H
diff --git a/src/aircraft_gui.cpp b/src/aircraft_gui.cpp
--- a/src/aircraft_gui.cpp
+++ b/src/aircraft_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file aircraft_gui.cpp */
+/** @file aircraft_gui.cpp The GUI of aircraft. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/airport.cpp b/src/airport.cpp
--- a/src/airport.cpp
+++ b/src/airport.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file airport.cpp */
+/** @file airport.cpp Functions related to airports. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/airport_gui.cpp b/src/airport_gui.cpp
--- a/src/airport_gui.cpp
+++ b/src/airport_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file airport_gui.cpp */
+/** @file airport_gui.cpp The GUI for airports. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/animated_tile_func.h b/src/animated_tile_func.h
--- a/src/animated_tile_func.h
+++ b/src/animated_tile_func.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file animated_tile.h Tile animation! */
+/** @file animated_tile_func.h Tile animation! */
 
 #ifndef ANIMATED_TILE_H
 #define ANIMATED_TILE_H
diff --git a/src/articulated_vehicles.cpp b/src/articulated_vehicles.cpp
--- a/src/articulated_vehicles.cpp
+++ b/src/articulated_vehicles.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file articulated_vehicles.cpp */
+/** @file articulated_vehicles.cpp Implementation of articulated vehicles. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/articulated_vehicles.h b/src/articulated_vehicles.h
--- a/src/articulated_vehicles.h
+++ b/src/articulated_vehicles.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file articulated_vehicles.h */
+/** @file articulated_vehicles.h Functions related to articulated vehicles. */
 
 #ifndef ARTICULATED_VEHICLES_H
 #define ARTICULATED_VEHICLES_H
diff --git a/src/autoreplace_gui.cpp b/src/autoreplace_gui.cpp
--- a/src/autoreplace_gui.cpp
+++ b/src/autoreplace_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file autoreplace_gui.cpp */
+/** @file autoreplace_gui.cpp GUI for autoreplace handling. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/autoslope.h b/src/autoslope.h
--- a/src/autoslope.h
+++ b/src/autoslope.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file autoslope.h */
+/** @file autoslope.h Functions related to autoslope. */
 
 #ifndef AUTOSLOPE_H
 #define AUTOSLOPE_H
diff --git a/src/aystar.cpp b/src/aystar.cpp
--- a/src/aystar.cpp
+++ b/src/aystar.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file aystar.cpp */
+/** @file aystar.cpp Implementation of A*. */
 
 /*
  * This file has the core function for AyStar
diff --git a/src/blitter/32bpp_anim.cpp b/src/blitter/32bpp_anim.cpp
--- a/src/blitter/32bpp_anim.cpp
+++ b/src/blitter/32bpp_anim.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file 32bpp_anim.cpp Implementation of the optimized 32 bpp blitter with animation support. */
+
 #include "../stdafx.h"
 #include "../core/alloc_func.hpp"
 #include "../gfx_func.h"
diff --git a/src/blitter/32bpp_anim.hpp b/src/blitter/32bpp_anim.hpp
--- a/src/blitter/32bpp_anim.hpp
+++ b/src/blitter/32bpp_anim.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file 32bpp_anim.hpp */
+/** @file 32bpp_anim.hpp A 32 bpp blitter with animation support. */
 
 #ifndef BLITTER_32BPP_ANIM_HPP
 #define BLITTER_32BPP_ANIM_HPP
diff --git a/src/blitter/32bpp_base.cpp b/src/blitter/32bpp_base.cpp
--- a/src/blitter/32bpp_base.cpp
+++ b/src/blitter/32bpp_base.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file 32bpp_base.cpp Implementation of base for 32 bpp blitters. */
+
 #include "../stdafx.h"
 #include "../gfx_func.h"
 #include "32bpp_base.hpp"
diff --git a/src/blitter/32bpp_base.hpp b/src/blitter/32bpp_base.hpp
--- a/src/blitter/32bpp_base.hpp
+++ b/src/blitter/32bpp_base.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file 32bpp_base.hpp */
+/** @file 32bpp_base.hpp Base for all 32 bits blitters. */
 
 #ifndef BLITTER_32BPP_BASE_HPP
 #define BLITTER_32BPP_BASE_HPP
diff --git a/src/blitter/32bpp_optimized.cpp b/src/blitter/32bpp_optimized.cpp
--- a/src/blitter/32bpp_optimized.cpp
+++ b/src/blitter/32bpp_optimized.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file 32bpp_optimized.cpp Implementation of the optimized 32 bpp blitter. */
+
 #include "../stdafx.h"
 #include "../zoom_func.h"
 #include "../gfx_func.h"
diff --git a/src/blitter/32bpp_optimized.hpp b/src/blitter/32bpp_optimized.hpp
--- a/src/blitter/32bpp_optimized.hpp
+++ b/src/blitter/32bpp_optimized.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file 32bpp_optimized.hpp */
+/** @file 32bpp_optimized.hpp Optimized 32 bpp blitter. */
 
 #ifndef BLITTER_32BPP_OPTIMIZED_HPP
 #define BLITTER_32BPP_OPTIMIZED_HPP
diff --git a/src/blitter/32bpp_simple.cpp b/src/blitter/32bpp_simple.cpp
--- a/src/blitter/32bpp_simple.cpp
+++ b/src/blitter/32bpp_simple.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file 32bpp_simple.cpp Implementation of the simple 32 bpp blitter. */
+
 #include "../stdafx.h"
 #include "../gfx_func.h"
 #include "../zoom_func.h"
diff --git a/src/blitter/32bpp_simple.hpp b/src/blitter/32bpp_simple.hpp
--- a/src/blitter/32bpp_simple.hpp
+++ b/src/blitter/32bpp_simple.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file 32bpp_simple.hpp */
+/** @file 32bpp_simple.hpp Simple 32 bpp blitter. */
 
 #ifndef BLITTER_32BPP_SIMPLE_HPP
 #define BLITTER_32BPP_SIMPLE_HPP
diff --git a/src/blitter/8bpp_base.cpp b/src/blitter/8bpp_base.cpp
--- a/src/blitter/8bpp_base.cpp
+++ b/src/blitter/8bpp_base.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file 8bpp_base.cpp Implementation of the base for all 8 bpp blitters. */
+
 #include "../stdafx.h"
 #include "../gfx_func.h"
 #include "8bpp_base.hpp"
diff --git a/src/blitter/8bpp_base.hpp b/src/blitter/8bpp_base.hpp
--- a/src/blitter/8bpp_base.hpp
+++ b/src/blitter/8bpp_base.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file 8bpp_base.hpp */
+/** @file 8bpp_base.hpp Base for all 8 bpp blitters. */
 
 #ifndef BLITTER_8BPP_BASE_HPP
 #define BLITTER_8BPP_BASE_HPP
diff --git a/src/blitter/8bpp_debug.cpp b/src/blitter/8bpp_debug.cpp
--- a/src/blitter/8bpp_debug.cpp
+++ b/src/blitter/8bpp_debug.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file 8bpp_debug.cpp */
+/** @file 8bpp_debug.cpp Implementation of 8 bpp debug blitter. */
 
 #include "../stdafx.h"
 #include "../zoom_func.h"
diff --git a/src/blitter/8bpp_debug.hpp b/src/blitter/8bpp_debug.hpp
--- a/src/blitter/8bpp_debug.hpp
+++ b/src/blitter/8bpp_debug.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file 8bpp_debug.hpp */
+/** @file 8bpp_debug.hpp A 8 bpp blitter that uses random colours to show the drawn sprites. */
 
 #ifndef BLITTER_8BPP_DEBUG_HPP
 #define BLITTER_8BPP_DEBUG_HPP
diff --git a/src/blitter/8bpp_optimized.cpp b/src/blitter/8bpp_optimized.cpp
--- a/src/blitter/8bpp_optimized.cpp
+++ b/src/blitter/8bpp_optimized.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file 8bpp_optimized.cpp */
+/** @file 8bpp_optimized.cpp Implementation of the optimized 8 bpp blitter. */
 
 #include "../stdafx.h"
 #include "../zoom_func.h"
diff --git a/src/blitter/8bpp_optimized.hpp b/src/blitter/8bpp_optimized.hpp
--- a/src/blitter/8bpp_optimized.hpp
+++ b/src/blitter/8bpp_optimized.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file 8bpp_optimized.hpp */
+/** @file 8bpp_optimized.hpp An optimized 8 bpp blitter. */
 
 #ifndef BLITTER_8BPP_OPTIMIZED_HPP
 #define BLITTER_8BPP_OPTIMIZED_HPP
diff --git a/src/blitter/8bpp_simple.cpp b/src/blitter/8bpp_simple.cpp
--- a/src/blitter/8bpp_simple.cpp
+++ b/src/blitter/8bpp_simple.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file 8bpp_simple.cpp */
+/** @file 8bpp_simple.cpp Implementation of the simple 8 bpp blitter. */
 
 #include "../stdafx.h"
 #include "../zoom_func.h"
diff --git a/src/blitter/8bpp_simple.hpp b/src/blitter/8bpp_simple.hpp
--- a/src/blitter/8bpp_simple.hpp
+++ b/src/blitter/8bpp_simple.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file 8bpp_simple.hpp */
+/** @file 8bpp_simple.hpp Simple (and slow) 8 bpp blitter. */
 
 #ifndef BLITTER_8BPP_SIMPLE_HPP
 #define BLITTER_8BPP_SIMPLE_HPP
diff --git a/src/blitter/base.hpp b/src/blitter/base.hpp
--- a/src/blitter/base.hpp
+++ b/src/blitter/base.hpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file base.hpp Base for all blitters. */
+
 #ifndef BLITTER_BASE_HPP
 #define BLITTER_BASE_HPP
 
diff --git a/src/blitter/factory.hpp b/src/blitter/factory.hpp
--- a/src/blitter/factory.hpp
+++ b/src/blitter/factory.hpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file factory.hpp Factory to 'query' all available blitters. */
+
 #ifndef BLITTER_FACTORY_HPP
 #define BLITTER_FACTORY_HPP
 
diff --git a/src/blitter/null.hpp b/src/blitter/null.hpp
--- a/src/blitter/null.hpp
+++ b/src/blitter/null.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file null.hpp */
+/** @file null.hpp The blitter that doesn't blit. */
 
 #ifndef BLITTER_NULL_HPP
 #define BLITTER_NULL_HPP
diff --git a/src/bmp.cpp b/src/bmp.cpp
--- a/src/bmp.cpp
+++ b/src/bmp.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file bmp.cpp */
+/** @file bmp.cpp Read and write support for bmps. */
 
 #include "stdafx.h"
 #include "bmp.h"
diff --git a/src/bmp.h b/src/bmp.h
--- a/src/bmp.h
+++ b/src/bmp.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file bmp.h */
+/** @file bmp.h Read and write support for bmps. */
 
 #ifndef BMP_H
 #define BMP_H
diff --git a/src/build_vehicle_gui.cpp b/src/build_vehicle_gui.cpp
--- a/src/build_vehicle_gui.cpp
+++ b/src/build_vehicle_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file build_vehicle_gui.cpp */
+/** @file build_vehicle_gui.cpp GUI for building vehicles. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/callback_table.cpp b/src/callback_table.cpp
--- a/src/callback_table.cpp
+++ b/src/callback_table.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file callback_table.cpp */
+/** @file callback_table.cpp All command callbacks. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/callback_table.h b/src/callback_table.h
--- a/src/callback_table.h
+++ b/src/callback_table.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file callback_table.h  */
+/** @file callback_table.h Table with all command callbacks. */
 
 #ifndef CALLBACK_TABLE_H
 #define CALLBACK_TABLE_H
diff --git a/src/cargopacket.h b/src/cargopacket.h
--- a/src/cargopacket.h
+++ b/src/cargopacket.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file cargopacket.h */
+/** @file cargopacket.h Base class for cargo packets. */
 
 #ifndef CARGOPACKET_H
 #define CARGOPACKET_H
diff --git a/src/cargotype.cpp b/src/cargotype.cpp
--- a/src/cargotype.cpp
+++ b/src/cargotype.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file cargotype.cpp */
+/** @file cargotype.cpp Implementation of cargos. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/cargotype.h b/src/cargotype.h
--- a/src/cargotype.h
+++ b/src/cargotype.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file cargotype.h */
+/** @file cargotype.h Types/functions related to cargos. */
 
 #ifndef CARGOTYPE_H
 #define CARGOTYPE_H
diff --git a/src/cheat.cpp b/src/cheat.cpp
--- a/src/cheat.cpp
+++ b/src/cheat.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file misc.cpp */
+/** @file cheat.cpp Handling (loading/saving/initializing) of cheats. */
 
 #include "stdafx.h"
 #include "saveload.h"
diff --git a/src/cheat_gui.cpp b/src/cheat_gui.cpp
--- a/src/cheat_gui.cpp
+++ b/src/cheat_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file misc_gui.cpp */
+/** @file cheat_gui.cpp GUI related to cheating. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/clear_cmd.cpp b/src/clear_cmd.cpp
--- a/src/clear_cmd.cpp
+++ b/src/clear_cmd.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file clear_cmd.cpp */
+/** @file clear_cmd.cpp Commands related to clear tiles. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/cmd_helper.h b/src/cmd_helper.h
--- a/src/cmd_helper.h
+++ b/src/cmd_helper.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file cmd_helper.h Helper functions to extract data from command parameters. */
+
 #ifndef CMD_HELPER_H
 #define CMD_HELPER_H
 
diff --git a/src/command.cpp b/src/command.cpp
--- a/src/command.cpp
+++ b/src/command.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file command.cpp */
+/** @file command.cpp Handling of commands. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/console.cpp b/src/console.cpp
--- a/src/console.cpp
+++ b/src/console.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file console.cpp */
+/** @file console.cpp Handling of the in-game console. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/console.h b/src/console.h
--- a/src/console.h
+++ b/src/console.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file console.h */
+/** @file console.h In-game console. */
 
 #ifndef CONSOLE_H
 #define CONSOLE_H
diff --git a/src/console_cmds.cpp b/src/console_cmds.cpp
--- a/src/console_cmds.cpp
+++ b/src/console_cmds.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file console_cmds.cpp */
+/** @file console_cmds.cpp Implementation of the console hooks. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/core/alloc_func.cpp b/src/core/alloc_func.cpp
--- a/src/core/alloc_func.cpp
+++ b/src/core/alloc_func.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file alloc_func.cpp functions to 'handle' memory allocation errors */
+/** @file alloc_func.cpp Functions to 'handle' memory allocation errors */
 
 #include "../stdafx.h"
 #include "alloc_func.hpp"
diff --git a/src/core/alloc_type.hpp b/src/core/alloc_type.hpp
--- a/src/core/alloc_type.hpp
+++ b/src/core/alloc_type.hpp
@@ -1,4 +1,3 @@
-
 /* $Id$ */
 
 /** @file alloc_type.hpp Helper types related to the allocation of memory */
diff --git a/src/core/bitmath_func.cpp b/src/core/bitmath_func.cpp
--- a/src/core/bitmath_func.cpp
+++ b/src/core/bitmath_func.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file bitmath_func.cpp */
+/** @file bitmath_func.cpp Functions related to bit mathematics. */
 
 #include "../stdafx.h"
 #include "bitmath_func.hpp"
diff --git a/src/core/bitmath_func.hpp b/src/core/bitmath_func.hpp
--- a/src/core/bitmath_func.hpp
+++ b/src/core/bitmath_func.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file bitmath_func.hpp */
+/** @file bitmath_func.hpp Functions related to bit mathematics. */
 
 #ifndef BITMATH_FUNC_HPP
 #define BITMATH_FUNC_HPP
diff --git a/src/core/endian_func.hpp b/src/core/endian_func.hpp
--- a/src/core/endian_func.hpp
+++ b/src/core/endian_func.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file endian_func.hpp */
+/** @file endian_func.hpp Function to handling different endian machines. */
 
 #ifndef ENDIAN_FUNC_H
 #define ENDIAN_FUNC_H
diff --git a/src/core/random_func.cpp b/src/core/random_func.cpp
--- a/src/core/random_func.cpp
+++ b/src/core/random_func.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file random_func.cpp */
+/** @file random_func.cpp Implementation of the pseudo random generator. */
 
 #include "../stdafx.h"
 #include "random_func.hpp"
diff --git a/src/core/random_func.hpp b/src/core/random_func.hpp
--- a/src/core/random_func.hpp
+++ b/src/core/random_func.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file random_func.hpp */
+/** @file random_func.hpp Pseudo random number generator. */
 
 #ifndef RANDOM_FUNC_HPP
 #define RANDOM_FUNC_HPP
diff --git a/src/currency.cpp b/src/currency.cpp
--- a/src/currency.cpp
+++ b/src/currency.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file currency.cpp **/
+/** @file currency.cpp Support for different currencies. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/currency.h b/src/currency.h
--- a/src/currency.h
+++ b/src/currency.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file currency.h */
+/** @file currency.h Functions to handle different currencies. */
 
 #ifndef CURRENCY_H
 #define CURRENCY_H
diff --git a/src/date.cpp b/src/date.cpp
--- a/src/date.cpp
+++ b/src/date.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file date.cpp */
+/** @file date.cpp Handling of dates in our native format and transforming them to something human readable. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/debug.cpp b/src/debug.cpp
--- a/src/debug.cpp
+++ b/src/debug.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file debug.cpp */
+/** @file debug.cpp Handling of printing debug messages. */
 
 #include "stdafx.h"
 #include <stdio.h>
diff --git a/src/debug.h b/src/debug.h
--- a/src/debug.h
+++ b/src/debug.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file debug.h */
+/** @file debug.h Functions related to debugging. */
 
 #ifndef DEBUG_H
 #define DEBUG_H
diff --git a/src/dedicated.cpp b/src/dedicated.cpp
--- a/src/dedicated.cpp
+++ b/src/dedicated.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file dedicated.cpp */
+/** @file dedicated.cpp Forking support for dedicated servers. */
 
 #include "stdafx.h"
 
diff --git a/src/depot.cpp b/src/depot.cpp
--- a/src/depot.cpp
+++ b/src/depot.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file depot.cpp */
+/** @file depot.cpp Handling of depots. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/depot_base.h b/src/depot_base.h
--- a/src/depot_base.h
+++ b/src/depot_base.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file depot.h Base for all depots (except hangars) */
+/** @file depot_base.h Base for all depots (except hangars) */
 
 #ifndef DEPOT_BASE_H
 #define DEPOT_BASE_H
diff --git a/src/depot_gui.cpp b/src/depot_gui.cpp
--- a/src/depot_gui.cpp
+++ b/src/depot_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file depot_gui.cpp */
+/** @file depot_gui.cpp The GUI for depots. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/dock_gui.cpp b/src/dock_gui.cpp
--- a/src/dock_gui.cpp
+++ b/src/dock_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file dock_gui.cpp */
+/** @file dock_gui.cpp GUI to create amazing water objects. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/driver.cpp b/src/driver.cpp
--- a/src/driver.cpp
+++ b/src/driver.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file driver.cpp */
+/** @file driver.cpp Base for all driver handling. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/driver.h b/src/driver.h
--- a/src/driver.h
+++ b/src/driver.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file driver.h */
+/** @file driver.h Base for all drivers (video, sound, music, etc). */
 
 #ifndef DRIVER_H
 #define DRIVER_H
diff --git a/src/dummy_land.cpp b/src/dummy_land.cpp
--- a/src/dummy_land.cpp
+++ b/src/dummy_land.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file dummy_land.cpp */
+/** @file dummy_land.cpp Handling of void (or dummy) tiles. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/economy.cpp b/src/economy.cpp
--- a/src/economy.cpp
+++ b/src/economy.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file economy.cpp */
+/** @file economy.cpp Handling of the economy. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/effectvehicle.cpp b/src/effectvehicle.cpp
--- a/src/effectvehicle.cpp
+++ b/src/effectvehicle.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file vehicle.cpp */
+/** @file effectvehicle.cpp Implementation of everything generic to vehicles. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/effectvehicle_func.h b/src/effectvehicle_func.h
--- a/src/effectvehicle_func.h
+++ b/src/effectvehicle_func.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file effectvehicle.h Functions related to effect vehicles. */
+/** @file effectvehicle_func.h Functions related to effect vehicles. */
 
 #ifndef EFFECTVEHICLE_FUNC_H
 #define EFFECTVEHICLE_FUNC_H
diff --git a/src/elrail.cpp b/src/elrail.cpp
--- a/src/elrail.cpp
+++ b/src/elrail.cpp
@@ -1,4 +1,5 @@
 /* $Id$ */
+
 /** @file elrail.cpp
  * This file deals with displaying wires and pylons for electric railways.
  * <h2>Basics</h2>
diff --git a/src/engine.cpp b/src/engine.cpp
--- a/src/engine.cpp
+++ b/src/engine.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file engine.cpp */
+/** @file engine.cpp Base for all engine handling. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/engine_func.h b/src/engine_func.h
--- a/src/engine_func.h
+++ b/src/engine_func.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file engine_func.h */
+/** @file engine_func.h Functions related to engines. */
 
 #ifndef ENGINE_H
 #define ENGINE_H
diff --git a/src/engine_gui.cpp b/src/engine_gui.cpp
--- a/src/engine_gui.cpp
+++ b/src/engine_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file engine_gui.cpp */
+/** @file engine_gui.cpp GUI to show engine related information. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/fiber.hpp b/src/fiber.hpp
--- a/src/fiber.hpp
+++ b/src/fiber.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file fiber.hpp */
+/** @file fiber.hpp Base for all fiber related classes. */
 
 #ifndef FIBER_HPP
 #define FIBER_HPP
diff --git a/src/fontcache.cpp b/src/fontcache.cpp
--- a/src/fontcache.cpp
+++ b/src/fontcache.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file fontcache.cpp */
+/** @file fontcache.cpp Cache for characters from fonts. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/fontcache.h b/src/fontcache.h
--- a/src/fontcache.h
+++ b/src/fontcache.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file fontcache.h Functions to read fonts from files and cache them. */
+
 #ifndef FONTCACHE_H
 #define FONTCACHE_H
 
diff --git a/src/functions.h b/src/functions.h
--- a/src/functions.h
+++ b/src/functions.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file functions.h */
+/** @file functions.h Some generic functions that actually shouldn't be here. */
 
 #ifndef FUNCTIONS_H
 #define FUNCTIONS_H
diff --git a/src/genworld.cpp b/src/genworld.cpp
--- a/src/genworld.cpp
+++ b/src/genworld.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file genworld.cpp */
+/** @file genworld.cpp Functions to generate a map. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/genworld.h b/src/genworld.h
--- a/src/genworld.h
+++ b/src/genworld.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file genworld.h */
+/** @file genworld.h Functions related to world/map generation. */
 
 #ifndef GENWORLD_H
 #define GENWORLD_H
diff --git a/src/genworld_gui.cpp b/src/genworld_gui.cpp
--- a/src/genworld_gui.cpp
+++ b/src/genworld_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file genworld_gui.cpp */
+/** @file genworld_gui.cpp GUI to configure and show progress during map generation. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/gfx.cpp b/src/gfx.cpp
--- a/src/gfx.cpp
+++ b/src/gfx.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file gfx.cpp */
+/** @file gfx.cpp Handling of drawing text and other gfx related stuff. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/gfxinit.cpp b/src/gfxinit.cpp
--- a/src/gfxinit.cpp
+++ b/src/gfxinit.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file gfxinit.cpp */
+/** @file gfxinit.cpp Initializing of the (GRF) graphics. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/gfxinit.h b/src/gfxinit.h
--- a/src/gfxinit.h
+++ b/src/gfxinit.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file gfxinit.h */
+/** @file gfxinit.h Functions related to the graphics initialization. */
 
 #ifndef GFXINIT_H
 #define GFXINIT_H
diff --git a/src/graph_gui.cpp b/src/graph_gui.cpp
--- a/src/graph_gui.cpp
+++ b/src/graph_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file graph_gui.cpp */
+/** @file graph_gui.cpp GUI that shows performance graphs. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/group.h b/src/group.h
--- a/src/group.h
+++ b/src/group.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file group.h */
+/** @file group.h Base class from groups. */
 
 #ifndef GROUP_H
 #define GROUP_H
diff --git a/src/group_gui.cpp b/src/group_gui.cpp
--- a/src/group_gui.cpp
+++ b/src/group_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file group_gui.cpp */
+/** @file group_gui.cpp GUI for the group window. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/gui.h b/src/gui.h
--- a/src/gui.h
+++ b/src/gui.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file gui.h */
+/** @file gui.h GUI functions that shouldn't be here. */
 
 #ifndef GUI_H
 #define GUI_H
diff --git a/src/heightmap.cpp b/src/heightmap.cpp
--- a/src/heightmap.cpp
+++ b/src/heightmap.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file heightmap.cpp */
+/** @file heightmap.cpp Creating of maps from heightmaps. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/heightmap.h b/src/heightmap.h
--- a/src/heightmap.h
+++ b/src/heightmap.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file heightmap.h */
+/** @file heightmap.h Functions related to creating heightmaps from files. */
 
 #ifndef HEIGHTMAP_H
 #define HEIGHTMAP_H
diff --git a/src/helpers.cpp b/src/helpers.cpp
--- a/src/helpers.cpp
+++ b/src/helpers.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file helpers.cpp */
+/** @file helpers.cpp Some not-so-generic helper functions. */
 
 #include "stdafx.h"
 
diff --git a/src/industry.h b/src/industry.h
--- a/src/industry.h
+++ b/src/industry.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file industry.h */
+/** @file industry.h Base of all industries. */
 
 #ifndef INDUSTRY_H
 #define INDUSTRY_H
diff --git a/src/industry_cmd.cpp b/src/industry_cmd.cpp
--- a/src/industry_cmd.cpp
+++ b/src/industry_cmd.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file industry_cmd.cpp */
+/** @file industry_cmd.cpp Handling of industry tiles. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/industry_gui.cpp b/src/industry_gui.cpp
--- a/src/industry_gui.cpp
+++ b/src/industry_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file industry_gui.cpp */
+/** @file industry_gui.cpp GUIs related to industries. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/intro_gui.cpp b/src/intro_gui.cpp
--- a/src/intro_gui.cpp
+++ b/src/intro_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file intro_gui.cpp */
+/** @file intro_gui.cpp The main menu GUI. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/landscape.cpp b/src/landscape.cpp
--- a/src/landscape.cpp
+++ b/src/landscape.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file landscape.cpp Functions related to the landscape (slopes etc.). */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "bridge_map.h"
diff --git a/src/landscape.h b/src/landscape.h
--- a/src/landscape.h
+++ b/src/landscape.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file landscape.h */
+/** @file landscape.h Functions related to OTTD's landscape. */
 
 #ifndef LANDSCAPE_H
 #define LANDSCAPE_H
diff --git a/src/livery.h b/src/livery.h
--- a/src/livery.h
+++ b/src/livery.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file livery.h */
+/** @file livery.h Functions/types related to livery colours. */
 
 #ifndef LIVERY_H
 #define LIVERY_H
diff --git a/src/main_gui.cpp b/src/main_gui.cpp
--- a/src/main_gui.cpp
+++ b/src/main_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file main_gui.cpp */
+/** @file main_gui.cpp Handling of the main viewport. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/map.cpp b/src/map.cpp
--- a/src/map.cpp
+++ b/src/map.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file map.cpp */
+/** @file map.cpp Base functions related to the map and distances on them. */
 
 #include "stdafx.h"
 #include "debug.h"
diff --git a/src/map_func.h b/src/map_func.h
--- a/src/map_func.h
+++ b/src/map_func.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file map_func.h */
+/** @file map_func.h Functions related to maps. */
 
 #ifndef MAP_FUNC_H
 #define MAP_FUNC_H
diff --git a/src/md5.cpp b/src/md5.cpp
--- a/src/md5.cpp
+++ b/src/md5.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file md5.cpp */
+/** @file md5.cpp Creating MD5 checksums of files. */
 
 /*
   Copyright (C) 1999, 2000, 2002 Aladdin Enterprises.  All rights reserved.
diff --git a/src/md5.h b/src/md5.h
--- a/src/md5.h
+++ b/src/md5.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file md5.h */
+/** @file md5.h Functions to create MD5 checksums. */
 
 /*
   Copyright (C) 1999, 2002 Aladdin Enterprises.  All rights reserved.
diff --git a/src/minilzo.cpp b/src/minilzo.cpp
--- a/src/minilzo.cpp
+++ b/src/minilzo.cpp
@@ -1,39 +1,38 @@
 /* $Id$ */
 
-/* @file minilzo.cpp -- mini subset of the LZO real-time data compression library
-
-   This file is part of the LZO real-time data compression library.
-
-   Copyright (C) 2002 Markus Franz Xaver Johannes Oberhumer
-   Copyright (C) 2001 Markus Franz Xaver Johannes Oberhumer
-   Copyright (C) 2000 Markus Franz Xaver Johannes Oberhumer
-   Copyright (C) 1999 Markus Franz Xaver Johannes Oberhumer
-   Copyright (C) 1998 Markus Franz Xaver Johannes Oberhumer
-   Copyright (C) 1997 Markus Franz Xaver Johannes Oberhumer
-   Copyright (C) 1996 Markus Franz Xaver Johannes Oberhumer
-   All Rights Reserved.
-
-   The LZO library is free software; you can redistribute it and/or
-   modify it under the terms of the GNU General Public License as
-   published by the Free Software Foundation; either version 2 of
-   the License, or (at your option) any later version.
-
-   The LZO library is distributed in the hope that it will be useful,
-   but WITHOUT ANY WARRANTY; without even the implied warranty of
-   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-   GNU General Public License for more details.
-
-   You should have received a copy of the GNU General Public License
-   along with the LZO library; see the file COPYING.
-   If not, write to the Free Software Foundation, Inc.,
-   59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-
-   Markus F.X.J. Oberhumer
-   <markus@oberhumer.com>
-   http://www.oberhumer.com/opensource/lzo/
- */
-
-/*
+/**
+ * @file minilzo.cpp -- mini subset of the LZO real-time data compression library
+ *
+ * This file is part of the LZO real-time data compression library.
+ *
+ * Copyright (C) 2002 Markus Franz Xaver Johannes Oberhumer
+ * Copyright (C) 2001 Markus Franz Xaver Johannes Oberhumer
+ * Copyright (C) 2000 Markus Franz Xaver Johannes Oberhumer
+ * Copyright (C) 1999 Markus Franz Xaver Johannes Oberhumer
+ * Copyright (C) 1998 Markus Franz Xaver Johannes Oberhumer
+ * Copyright (C) 1997 Markus Franz Xaver Johannes Oberhumer
+ * Copyright (C) 1996 Markus Franz Xaver Johannes Oberhumer
+ * All Rights Reserved.
+ *
+ * The LZO library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License as
+ * published by the Free Software Foundation; either version 2 of
+ * the License, or (at your option) any later version.
+ *
+ * The LZO library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with the LZO library; see the file COPYING.
+ * If not, write to the Free Software Foundation, Inc.,
+ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ *
+ * Markus F.X.J. Oberhumer
+ * <markus@oberhumer.com>
+ * http://www.oberhumer.com/opensource/lzo/
+ *
  * NOTE:
  *   the full LZO package can be found at
  *   http://www.oberhumer.com/opensource/lzo/
diff --git a/src/minilzo.h b/src/minilzo.h
--- a/src/minilzo.h
+++ b/src/minilzo.h
@@ -1,45 +1,43 @@
 /* $Id$ */
 
-/* @file minilzo.h -- mini subset of the LZO real-time data compression library
-
-   This file is part of the LZO real-time data compression library.
-
-   Copyright (C) 2002 Markus Franz Xaver Johannes Oberhumer
-   Copyright (C) 2001 Markus Franz Xaver Johannes Oberhumer
-   Copyright (C) 2000 Markus Franz Xaver Johannes Oberhumer
-   Copyright (C) 1999 Markus Franz Xaver Johannes Oberhumer
-   Copyright (C) 1998 Markus Franz Xaver Johannes Oberhumer
-   Copyright (C) 1997 Markus Franz Xaver Johannes Oberhumer
-   Copyright (C) 1996 Markus Franz Xaver Johannes Oberhumer
-   All Rights Reserved.
-
-   The LZO library is free software; you can redistribute it and/or
-   modify it under the terms of the GNU General Public License as
-   published by the Free Software Foundation; either version 2 of
-   the License, or (at your option) any later version.
-
-   The LZO library is distributed in the hope that it will be useful,
-   but WITHOUT ANY WARRANTY; without even the implied warranty of
-   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-   GNU General Public License for more details.
-
-   You should have received a copy of the GNU General Public License
-   along with the LZO library; see the file COPYING.
-   If not, write to the Free Software Foundation, Inc.,
-   59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-
-   Markus F.X.J. Oberhumer
-   <markus@oberhumer.com>
-   http://www.oberhumer.com/opensource/lzo/
- */
-
-/*
+/**
+ * @file minilzo.h Mini subset of the LZO real-time data compression library
+ *
+ * This file is part of the LZO real-time data compression library.
+ *
+ * Copyright (C) 2002 Markus Franz Xaver Johannes Oberhumer
+ * Copyright (C) 2001 Markus Franz Xaver Johannes Oberhumer
+ * Copyright (C) 2000 Markus Franz Xaver Johannes Oberhumer
+ * Copyright (C) 1999 Markus Franz Xaver Johannes Oberhumer
+ * Copyright (C) 1998 Markus Franz Xaver Johannes Oberhumer
+ * Copyright (C) 1997 Markus Franz Xaver Johannes Oberhumer
+ * Copyright (C) 1996 Markus Franz Xaver Johannes Oberhumer
+ * All Rights Reserved.
+ *
+ * The LZO library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License as
+ * published by the Free Software Foundation; either version 2 of
+ * the License, or (at your option) any later version.
+ *
+ * The LZO library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with the LZO library; see the file COPYING.
+ * If not, write to the Free Software Foundation, Inc.,
+ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ *
+ * Markus F.X.J. Oberhumer
+ * <markus@oberhumer.com>
+ * http://www.oberhumer.com/opensource/lzo/
+ *
  * NOTE:
  *   the full LZO package can be found at
  *   http://www.oberhumer.com/opensource/lzo/
  */
 
-
 #ifndef MINILZO_H
 #define MINILZO_H
 
diff --git a/src/misc.cpp b/src/misc.cpp
--- a/src/misc.cpp
+++ b/src/misc.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file misc.cpp */
+/** @file misc.cpp Misc functions that shouldn't be here. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/misc/array.hpp b/src/misc/array.hpp
--- a/src/misc/array.hpp
+++ b/src/misc/array.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file array.hpp */
+/** @file array.hpp Array without an explicit maximum size. */
 
 #ifndef  ARRAY_HPP
 #define  ARRAY_HPP
diff --git a/src/misc/binaryheap.hpp b/src/misc/binaryheap.hpp
--- a/src/misc/binaryheap.hpp
+++ b/src/misc/binaryheap.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file binaryheap.hpp */
+/** @file binaryheap.hpp Binary heap implementation. */
 
 #ifndef  BINARYHEAP_HPP
 #define  BINARYHEAP_HPP
diff --git a/src/misc/blob.hpp b/src/misc/blob.hpp
--- a/src/misc/blob.hpp
+++ b/src/misc/blob.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file blob.hpp */
+/** @file blob.hpp Support for storing random binary data. */
 
 #ifndef BLOB_HPP
 #define BLOB_HPP
diff --git a/src/misc/countedobj.cpp b/src/misc/countedobj.cpp
--- a/src/misc/countedobj.cpp
+++ b/src/misc/countedobj.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file countedobj.cpp Support for reference counted objects. */
+
 #include "../stdafx.h"
 
 #include "countedptr.hpp"
diff --git a/src/misc/crc32.hpp b/src/misc/crc32.hpp
--- a/src/misc/crc32.hpp
+++ b/src/misc/crc32.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file crc32.hpp */
+/** @file crc32.hpp Cyclic reduncancy check support. */
 
 #ifndef  CRC32_HPP
 #define  CRC32_HPP
diff --git a/src/misc/dbg_helpers.cpp b/src/misc/dbg_helpers.cpp
--- a/src/misc/dbg_helpers.cpp
+++ b/src/misc/dbg_helpers.cpp
@@ -1,6 +1,7 @@
 /* $Id$ */
 
-/** @file dbg_helpers.cpp */
+/** @file dbg_helpers.cpp Helpers for outputting debug information. */
+
 #include "../stdafx.h"
 #include "../openttd.h"
 #include "../direction_type.h"
diff --git a/src/misc/dbg_helpers.h b/src/misc/dbg_helpers.h
--- a/src/misc/dbg_helpers.h
+++ b/src/misc/dbg_helpers.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file dbg_helpers.h */
+/** @file dbg_helpers.h Functions to be used for debug printings. */
 
 #ifndef DBG_HELPERS
 #define DBG_HELPERS
diff --git a/src/misc/fixedsizearray.hpp b/src/misc/fixedsizearray.hpp
--- a/src/misc/fixedsizearray.hpp
+++ b/src/misc/fixedsizearray.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file fixedsizearray.hpp */
+/** @file fixedsizearray.hpp A fixed size array that doesn't create items until needed. */
 
 #ifndef  FIXEDSIZEARRAY_HPP
 #define  FIXEDSIZEARRAY_HPP
diff --git a/src/misc/hashtable.hpp b/src/misc/hashtable.hpp
--- a/src/misc/hashtable.hpp
+++ b/src/misc/hashtable.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file hashtable.hpp */
+/** @file hashtable.hpp Hash table support. */
 
 #ifndef  HASHTABLE_HPP
 #define  HASHTABLE_HPP
diff --git a/src/misc/smallvec.h b/src/misc/smallvec.h
--- a/src/misc/smallvec.h
+++ b/src/misc/smallvec.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/* @file smallvec.h */
+/** @file smallvec.h Simple vector class that allows allocating an item without the need to copy data needlessly. */
 
 #ifndef SMALLVEC_H
 #define SMALLVEC_H
diff --git a/src/misc/str.hpp b/src/misc/str.hpp
--- a/src/misc/str.hpp
+++ b/src/misc/str.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file str.hpp */
+/** @file str.hpp String formating? */
 
 #ifndef  STR_HPP
 #define  STR_HPP
diff --git a/src/misc/strapi.hpp b/src/misc/strapi.hpp
--- a/src/misc/strapi.hpp
+++ b/src/misc/strapi.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file strapi.hpp */
+/** @file strapi.hpp More string formatting? */
 
 #ifndef  STRAPI_HPP
 #define  STRAPI_HPP
diff --git a/src/misc_cmd.cpp b/src/misc_cmd.cpp
--- a/src/misc_cmd.cpp
+++ b/src/misc_cmd.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file misc_cmd.cpp */
+/** @file misc_cmd.cpp Some misc functions that are better fitted in other files, but never got moved there... */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/misc_gui.cpp b/src/misc_gui.cpp
--- a/src/misc_gui.cpp
+++ b/src/misc_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file misc_gui.cpp */
+/** @file misc_gui.cpp GUIs for a number of misc windows. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/mixer.cpp b/src/mixer.cpp
--- a/src/mixer.cpp
+++ b/src/mixer.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file mixer.cpp*/
+/** @file mixer.cpp Mixing of sound samples. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/mixer.h b/src/mixer.h
--- a/src/mixer.h
+++ b/src/mixer.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file mixer.h */
+/** @file mixer.h Functions to mix sound samples. */
 
 #ifndef MIXER_H
 #define MIXER_H
diff --git a/src/music.cpp b/src/music.cpp
--- a/src/music.cpp
+++ b/src/music.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file music.cpp */
+/** @file music.cpp The songs that OpenTTD knows. */
 
 #include "stdafx.h"
 #include "music.h"
diff --git a/src/music.h b/src/music.h
--- a/src/music.h
+++ b/src/music.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file music.h */
+/** @file music.h Base for the music handling. */
 
 #ifndef MUSIC_H
 #define MUSIC_H
diff --git a/src/music/bemidi.cpp b/src/music/bemidi.cpp
--- a/src/music/bemidi.cpp
+++ b/src/music/bemidi.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file bemidi.cpp */
+/** @file bemidi.cpp Support for BeOS midi. */
 
 #include "../stdafx.h"
 #include "../openttd.h"
diff --git a/src/music/bemidi.h b/src/music/bemidi.h
--- a/src/music/bemidi.h
+++ b/src/music/bemidi.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file bemidi.h Base of BeOS Midi support. */
+
 #ifndef MUSIC_BEMIDI_H
 #define MUSIC_BEMIDI_H
 
diff --git a/src/music/dmusic.cpp b/src/music/dmusic.cpp
--- a/src/music/dmusic.cpp
+++ b/src/music/dmusic.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file dmusic.cpp */
+/** @file dmusic.cpp Playing music via DirectMusic. */
 
 #ifdef WIN32_ENABLE_DIRECTMUSIC_SUPPORT
 
diff --git a/src/music/dmusic.h b/src/music/dmusic.h
--- a/src/music/dmusic.h
+++ b/src/music/dmusic.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file dmusic.h Base of playing music via DirectMusic.
+
 #ifndef MUSIC_DMUSIC_H
 #define MUSIC_DMUSIC_H
 
diff --git a/src/music/extmidi.cpp b/src/music/extmidi.cpp
--- a/src/music/extmidi.cpp
+++ b/src/music/extmidi.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file extmidi.cpp Playing music via an external player. */
+
 #ifndef __MORPHOS__
 #include "../stdafx.h"
 #include "../openttd.h"
diff --git a/src/music/extmidi.h b/src/music/extmidi.h
--- a/src/music/extmidi.h
+++ b/src/music/extmidi.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file extmidi.h Base support for playing music via an external application. */
+
 #ifndef MUSIC_EXTERNAL_H
 #define MUSIC_EXTERNAL_H
 
diff --git a/src/music/libtimidity.cpp b/src/music/libtimidity.cpp
--- a/src/music/libtimidity.cpp
+++ b/src/music/libtimidity.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file libtimidity.cpp Playing music via the timidity library. */
+
 #include "../stdafx.h"
 #include "../openttd.h"
 #include "../sound_type.h"
diff --git a/src/music/libtimidity.h b/src/music/libtimidity.h
--- a/src/music/libtimidity.h
+++ b/src/music/libtimidity.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file libtimidity.h Base for LibTimidity music playback. */
+
 #ifndef MUSIC_LIBTIMIDITY_H
 #define MUSIC_LIBTIMIDITY_H
 
diff --git a/src/music/music_driver.hpp b/src/music/music_driver.hpp
--- a/src/music/music_driver.hpp
+++ b/src/music/music_driver.hpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file music_driver.hpp Base for all music playback. */
+
 #ifndef MUSIC_MUSIC_DRIVER_HPP
 #define MUSIC_MUSIC_DRIVER_HPP
 
diff --git a/src/music/null_m.cpp b/src/music/null_m.cpp
--- a/src/music/null_m.cpp
+++ b/src/music/null_m.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file null_m.cpp The music playback that is silent. */
+
 #include "../stdafx.h"
 #include "null_m.h"
 
diff --git a/src/music/null_m.h b/src/music/null_m.h
--- a/src/music/null_m.h
+++ b/src/music/null_m.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file null_m.h Base for the silent music playback. */
+
 #ifndef MUSIC_NULL_H
 #define MUSIC_NULL_H
 
diff --git a/src/music/os2_m.cpp b/src/music/os2_m.cpp
--- a/src/music/os2_m.cpp
+++ b/src/music/os2_m.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file os2_m.cpp Music playback on OS/2. */
+
 #include "../stdafx.h"
 #include "../openttd.h"
 #include "os2_m.h"
diff --git a/src/music/os2_m.h b/src/music/os2_m.h
--- a/src/music/os2_m.h
+++ b/src/music/os2_m.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file os2_m.h Base for OS2 music playback. */
+
 #ifndef MUSIC_OS2_H
 #define MUSIC_OS2_H
 
diff --git a/src/music/qtmidi.h b/src/music/qtmidi.h
--- a/src/music/qtmidi.h
+++ b/src/music/qtmidi.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file qtmidi.h Base of music playback via the QuickTime driver. */
+
 #ifndef MUSIC_MACOSX_QUICKTIME_H
 #define MUSIC_MACOSX_QUICKTIME_H
 
diff --git a/src/music/win32_m.cpp b/src/music/win32_m.cpp
--- a/src/music/win32_m.cpp
+++ b/src/music/win32_m.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file win32_m.cpp Music playback for Windows. */
+
 #include "../stdafx.h"
 #include "win32_m.h"
 #include <windows.h>
diff --git a/src/music/win32_m.h b/src/music/win32_m.h
--- a/src/music/win32_m.h
+++ b/src/music/win32_m.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file win32_m.h Base for Windows music playback. */
+
 #ifndef MUSIC_WIN32_H
 #define MUSIC_WIN32_H
 
diff --git a/src/music_gui.cpp b/src/music_gui.cpp
--- a/src/music_gui.cpp
+++ b/src/music_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file music_gui.cpp */
+/** @file music_gui.cpp GUI for the music playback. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/namegen.cpp b/src/namegen.cpp
--- a/src/namegen.cpp
+++ b/src/namegen.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file namegen.cpp */
+/** @file namegen.cpp Town name generators. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/namegen_func.h b/src/namegen_func.h
--- a/src/namegen_func.h
+++ b/src/namegen_func.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file namegen.h Town name generator stuff. */
+/** @file namegen_func.h Town name generator stuff. */
 
 #ifndef NAMEGEN_H
 #define NAMEGEN_H
diff --git a/src/network/network.cpp b/src/network/network.cpp
--- a/src/network/network.cpp
+++ b/src/network/network.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file network.cpp Base functions for networking support. */
+
 #include "../stdafx.h"
 #include "network_data.h"
 
diff --git a/src/network/network.h b/src/network/network.h
--- a/src/network/network.h
+++ b/src/network/network.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file network.h Basic functions/variables used all over the place. */
+
 #ifndef NETWORK_H
 #define NETWORK_H
 
diff --git a/src/network/network_client.cpp b/src/network/network_client.cpp
--- a/src/network/network_client.cpp
+++ b/src/network/network_client.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file network_client.cpp Client part of the network protocol. */
+
 #ifdef ENABLE_NETWORK
 
 #include "../stdafx.h"
diff --git a/src/network/network_client.h b/src/network/network_client.h
--- a/src/network/network_client.h
+++ b/src/network/network_client.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file network_client.h Client part of the network protocol. */
+
 #ifndef NETWORK_CLIENT_H
 #define NETWORK_CLIENT_H
 
diff --git a/src/network/network_data.cpp b/src/network/network_data.cpp
--- a/src/network/network_data.cpp
+++ b/src/network/network_data.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file network_data.cpp Command handling over network connections. */
+
 #ifdef ENABLE_NETWORK
 
 #include "../stdafx.h"
diff --git a/src/network/network_data.h b/src/network/network_data.h
--- a/src/network/network_data.h
+++ b/src/network/network_data.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file network_data.h Internal functions. */
+
 #ifndef NETWORK_DATA_H
 #define NETWORK_DATA_H
 
diff --git a/src/network/network_gamelist.h b/src/network/network_gamelist.h
--- a/src/network/network_gamelist.h
+++ b/src/network/network_gamelist.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file network_gamelist.h Handling of the list of games. */
+
 #ifndef NETWORK_GAMELIST_H
 #define NETWORK_GAMELIST_H
 
diff --git a/src/network/network_gui.cpp b/src/network/network_gui.cpp
--- a/src/network/network_gui.cpp
+++ b/src/network/network_gui.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file network_gui.cpp Implementation of the Network related GUIs. */
+
 #ifdef ENABLE_NETWORK
 #include "../stdafx.h"
 #include "../openttd.h"
diff --git a/src/network/network_gui.h b/src/network/network_gui.h
--- a/src/network/network_gui.h
+++ b/src/network/network_gui.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file network_gui.h GUIs related to networking. */
+
 #ifndef NETWORK_GUI_H
 #define NETWORK_GUI_H
 
diff --git a/src/network/network_internal.h b/src/network/network_internal.h
--- a/src/network/network_internal.h
+++ b/src/network/network_internal.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file network_internal.h Variables and function used internally. */
+
 #ifndef NETWORK_INTERNAL_H
 #define NETWORK_INTERNAL_H
 
diff --git a/src/network/network_server.cpp b/src/network/network_server.cpp
--- a/src/network/network_server.cpp
+++ b/src/network/network_server.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file network_server.cpp Server part of the network protocol. */
+
 #ifdef ENABLE_NETWORK
 
 #include "../stdafx.h"
diff --git a/src/network/network_server.h b/src/network/network_server.h
--- a/src/network/network_server.h
+++ b/src/network/network_server.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file network_server.h Server part of the network protocol. */
+
 #ifndef NETWORK_SERVER_H
 #define NETWORK_SERVER_H
 
diff --git a/src/network/network_udp.h b/src/network/network_udp.h
--- a/src/network/network_udp.h
+++ b/src/network/network_udp.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file network_udp.h Sending and receiving UDP messages. */
+
 #ifndef NETWORK_UDP_H
 #define NETWORK_UDP_H
 
diff --git a/src/newgrf.cpp b/src/newgrf.cpp
--- a/src/newgrf.cpp
+++ b/src/newgrf.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file newgrf.cpp */
+/** @file newgrf.cpp Base of all NewGRF support. */
 
 #include "stdafx.h"
 
diff --git a/src/newgrf.h b/src/newgrf.h
--- a/src/newgrf.h
+++ b/src/newgrf.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file newgrf.h */
+/** @file newgrf.h Base for the NewGRF implementation. */
 
 #ifndef NEWGRF_H
 #define NEWGRF_H
diff --git a/src/newgrf_callbacks.h b/src/newgrf_callbacks.h
--- a/src/newgrf_callbacks.h
+++ b/src/newgrf_callbacks.h
@@ -1,12 +1,10 @@
 /* $Id$ */
 
-/** @file newgrf_callbacks.h
- */
+/** @file newgrf_callbacks.h Callbacks that NewGRFs could implement. */
 
 #ifndef NEWGRF_CALLBACKS_H
 #define NEWGRF_CALLBACKS_H
 
-
 /**
  * List of implemented NewGRF callbacks.
  * Most of these callbacks are only triggered when the corresponding
diff --git a/src/newgrf_canal.cpp b/src/newgrf_canal.cpp
--- a/src/newgrf_canal.cpp
+++ b/src/newgrf_canal.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file newgrf_canal.cpp Implementation of NewGRF canals. */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "variables.h"
diff --git a/src/newgrf_canal.h b/src/newgrf_canal.h
--- a/src/newgrf_canal.h
+++ b/src/newgrf_canal.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file newgrf_canal.h Handling of NewGRF canals. */
+
 #ifndef NEWGRF_CANAL_H
 #define NEWGRF_CANAL_H
 
diff --git a/src/newgrf_cargo.cpp b/src/newgrf_cargo.cpp
--- a/src/newgrf_cargo.cpp
+++ b/src/newgrf_cargo.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file newgrf_cargo.cpp Implementation of NewGRF cargoes. */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "debug.h"
diff --git a/src/newgrf_cargo.h b/src/newgrf_cargo.h
--- a/src/newgrf_cargo.h
+++ b/src/newgrf_cargo.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file newgrf_cargo.h */
+/** @file newgrf_cargo.h Cargo support for NewGRFs. */
 
 #ifndef NEWGRF_CARGO_H
 #define NEWGRF_CARGO_H
diff --git a/src/newgrf_config.cpp b/src/newgrf_config.cpp
--- a/src/newgrf_config.cpp
+++ b/src/newgrf_config.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file newgrf_config.cpp */
+/** @file newgrf_config.cpp Finding NewGRFs and configuring them. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/newgrf_config.h b/src/newgrf_config.h
--- a/src/newgrf_config.h
+++ b/src/newgrf_config.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file newgrf_config.h */
+/** @file newgrf_config.h Functions to find and configure NewGRFs. */
 
 #ifndef NEWGRF_CONFIG_H
 #define NEWGRF_CONFIG_H
diff --git a/src/newgrf_engine.cpp b/src/newgrf_engine.cpp
--- a/src/newgrf_engine.cpp
+++ b/src/newgrf_engine.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file newgrf_engine.cpp */
+/** @file newgrf_engine.cpp NewGRF handling of engines. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/newgrf_engine.h b/src/newgrf_engine.h
--- a/src/newgrf_engine.h
+++ b/src/newgrf_engine.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file newgrf_engine.h */
+/** @file newgrf_engine.h Functions for NewGRF engines. */
 
 #ifndef NEWGRF_ENGINE_H
 #define NEWGRF_ENGINE_H
diff --git a/src/newgrf_generic.cpp b/src/newgrf_generic.cpp
--- a/src/newgrf_generic.cpp
+++ b/src/newgrf_generic.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file newgrf_generic.cpp Handling of generic feature callbacks. */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "variables.h"
diff --git a/src/newgrf_generic.h b/src/newgrf_generic.h
--- a/src/newgrf_generic.h
+++ b/src/newgrf_generic.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file newgrf_generic.h Functions related to generic callbacks. */
+
 #ifndef NEWGRF_GENERIC_H
 #define NEWGRF_GENERIC_H
 
diff --git a/src/newgrf_gui.cpp b/src/newgrf_gui.cpp
--- a/src/newgrf_gui.cpp
+++ b/src/newgrf_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file newgrf_gui.cpp */
+/** @file newgrf_gui.cpp GUI to change NewGRF settings. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/newgrf_house.cpp b/src/newgrf_house.cpp
--- a/src/newgrf_house.cpp
+++ b/src/newgrf_house.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file newgrf_house.cpp */
+/** @file newgrf_house.cpp Implementation of NewGRF houses. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/newgrf_house.h b/src/newgrf_house.h
--- a/src/newgrf_house.h
+++ b/src/newgrf_house.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file newgrf_house.h */
+/** @file newgrf_house.h Functions related to NewGRF houses. */
 
 #ifndef NEWGRF_HOUSE_H
 #define NEWGRF_HOUSE_H
diff --git a/src/newgrf_industries.cpp b/src/newgrf_industries.cpp
--- a/src/newgrf_industries.cpp
+++ b/src/newgrf_industries.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file newgrf_industries.cpp */
+/** @file newgrf_industries.cpp Handling of NewGRF industries. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/newgrf_industries.h b/src/newgrf_industries.h
--- a/src/newgrf_industries.h
+++ b/src/newgrf_industries.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file newgrf_industries.h */
+/** @file newgrf_industries.h Functions for NewGRF industries. */
 
 #ifndef NEWGRF_INDUSTRIES_H
 #define NEWGRF_INDUSTRIES_H
diff --git a/src/newgrf_industrytiles.cpp b/src/newgrf_industrytiles.cpp
--- a/src/newgrf_industrytiles.cpp
+++ b/src/newgrf_industrytiles.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file newgrf_industrytiles.cpp */
+/** @file newgrf_industrytiles.cpp NewGRF handling of industry tiles. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/newgrf_industrytiles.h b/src/newgrf_industrytiles.h
--- a/src/newgrf_industrytiles.h
+++ b/src/newgrf_industrytiles.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file newgrf_industrytiles.h */
+/** @file newgrf_industrytiles.h NewGRF handling of industry tiles. */
 
 #ifndef NEWGRF_INDUSTRYTILES_H
 #define NEWGRF_INDUSTRYTILES_H
diff --git a/src/newgrf_sound.cpp b/src/newgrf_sound.cpp
--- a/src/newgrf_sound.cpp
+++ b/src/newgrf_sound.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file newgrf_sound.cpp */
+/** @file newgrf_sound.cpp Handling NewGRF provided sounds. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/newgrf_sound.h b/src/newgrf_sound.h
--- a/src/newgrf_sound.h
+++ b/src/newgrf_sound.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file newgrf_sound.h */
+/** @file newgrf_sound.h Functions related to NewGRF provided sounds. */
 
 #ifndef NEWGRF_SOUND_H
 #define NEWGRF_SOUND_H
diff --git a/src/newgrf_spritegroup.cpp b/src/newgrf_spritegroup.cpp
--- a/src/newgrf_spritegroup.cpp
+++ b/src/newgrf_spritegroup.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file newgrf_spritegroup.cpp */
+/** @file newgrf_spritegroup.cpp Handling of primarily NewGRF action 2. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/newgrf_spritegroup.h b/src/newgrf_spritegroup.h
--- a/src/newgrf_spritegroup.h
+++ b/src/newgrf_spritegroup.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file newgrf_spritegroup.h */
+/** @file newgrf_spritegroup.h Action 2 handling. */
 
 #ifndef NEWGRF_SPRITEGROUP_H
 #define NEWGRF_SPRITEGROUP_H
diff --git a/src/newgrf_town.cpp b/src/newgrf_town.cpp
--- a/src/newgrf_town.cpp
+++ b/src/newgrf_town.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file newgrf_town.cpp */
+/** @file newgrf_town.cpp Implementation of the town part of NewGRF houses. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/newgrf_town.h b/src/newgrf_town.h
--- a/src/newgrf_town.h
+++ b/src/newgrf_town.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file newgrf_town.h */
+/** @file newgrf_town.h Functions to handle the town part of NewGRF towns. */
 
 #ifndef NEWGRF_TOWN_H
 #define NEWGRF_TOWN_H
diff --git a/src/newgrf_townname.h b/src/newgrf_townname.h
--- a/src/newgrf_townname.h
+++ b/src/newgrf_townname.h
@@ -1,13 +1,14 @@
 /* $Id$ */
+
+/** @file newgrf_townname.h
+ * Header of Action 0F "universal holder" structure and functions
+ */
+
 #ifndef NEWGRF_TOWNNAME_H
 #define NEWGRF_TOWNNAME_H
 
 #include "strings_type.h"
 
-/** @file newgrf_townname.h
- * Header of Action 0F "universal holder" structure and functions
- */
-
 struct NamePart {
 	byte prob;     ///< The relative probablity of the following name to appear in the bottom 7 bits.
 	union {
diff --git a/src/news_gui.cpp b/src/news_gui.cpp
--- a/src/news_gui.cpp
+++ b/src/news_gui.cpp
@@ -1,5 +1,6 @@
 /* $Id$ */
 
+/** @file news_gui.cpp GUI functions related to news messages. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/npf.cpp b/src/npf.cpp
--- a/src/npf.cpp
+++ b/src/npf.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file npf.cpp */
+/** @file npf.cpp Implementation of the NPF pathfinder. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/npf.h b/src/npf.h
--- a/src/npf.h
+++ b/src/npf.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file npf.h */
+/** @file npf.h New A* pathfinder. */
 
 #ifndef NPF_H
 #define NPF_H
diff --git a/src/oldloader.cpp b/src/oldloader.cpp
--- a/src/oldloader.cpp
+++ b/src/oldloader.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file oldloader.cpp */
+/** @file oldloader.cpp Loading of old TTD(patch) savegames. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/oldpool.cpp b/src/oldpool.cpp
--- a/src/oldpool.cpp
+++ b/src/oldpool.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file oldpool.cpp */
+/** @file oldpool.cpp Implementation of the old pool. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/oldpool.h b/src/oldpool.h
--- a/src/oldpool.h
+++ b/src/oldpool.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file oldpool.h */
+/** @file oldpool.h Base for the old pool. */
 
 #ifndef OLDPOOL_H
 #define OLDPOOL_H
diff --git a/src/oldpool_func.h b/src/oldpool_func.h
--- a/src/oldpool_func.h
+++ b/src/oldpool_func.h
@@ -1,6 +1,9 @@
 /* $Id$ */
 
+/** @file oldpool_func.h Functions related to the old pool. */
+
 #ifndef OLDPOOL_FUNC_H
+#define OLDPOOL_FUNC_H
 
 #include "oldpool.h"
 
diff --git a/src/openttd.cpp b/src/openttd.cpp
--- a/src/openttd.cpp
+++ b/src/openttd.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file openttd.cpp */
+/** @file openttd.cpp Functions related to starting OpenTTD. */
 
 #include "stdafx.h"
 
diff --git a/src/openttd.h b/src/openttd.h
--- a/src/openttd.h
+++ b/src/openttd.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file openttd.h */
+/** @file openttd.h Some generic types. */
 
 #ifndef OPENTTD_H
 #define OPENTTD_H
diff --git a/src/order_base.h b/src/order_base.h
--- a/src/order_base.h
+++ b/src/order_base.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file order_base.h */
+/** @file order_base.h Base class for orders. */
 
 #ifndef ORDER_BASE_H
 #define ORDER_BASE_H
diff --git a/src/order_cmd.cpp b/src/order_cmd.cpp
--- a/src/order_cmd.cpp
+++ b/src/order_cmd.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file order_cmd.cpp */
+/** @file order_cmd.cpp Handling of orders. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/order_gui.cpp b/src/order_gui.cpp
--- a/src/order_gui.cpp
+++ b/src/order_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file order_gui.cpp */
+/** @file order_gui.cpp GUI related to orders. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/os/macosx/G5_detector.cpp b/src/os/macosx/G5_detector.cpp
--- a/src/os/macosx/G5_detector.cpp
+++ b/src/os/macosx/G5_detector.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file G5_detector.cpp Detection for G5 machines (PowerPC). */
+
 #include <mach/mach.h>
 #include <mach/mach_host.h>
 #include <mach/host_info.h>
diff --git a/src/os/macosx/macos.h b/src/os/macosx/macos.h
--- a/src/os/macosx/macos.h
+++ b/src/os/macosx/macos.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file macos.h Functions related to MacOS support. */
+
 #ifndef MACOS_H
 #define MACOS_H
 
diff --git a/src/os/macosx/osx_stdafx.h b/src/os/macosx/osx_stdafx.h
--- a/src/os/macosx/osx_stdafx.h
+++ b/src/os/macosx/osx_stdafx.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file osx_stdafx.h OSX is different on some places. */
+
 #ifndef MACOS_STDAFX_H
 #define MACOS_STDAFX_H
 
diff --git a/src/os/macosx/splash.cpp b/src/os/macosx/splash.cpp
--- a/src/os/macosx/splash.cpp
+++ b/src/os/macosx/splash.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file splash.cpp Splash screen support for OSX. */
+
 #include "../../stdafx.h"
 #include "../../openttd.h"
 #include "../../variables.h"
diff --git a/src/os/macosx/splash.h b/src/os/macosx/splash.h
--- a/src/os/macosx/splash.h
+++ b/src/os/macosx/splash.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file splash.h Functions to support splash screens for OSX. */
+
 #ifndef SPLASH_H
 #define SPLASH_H
 
diff --git a/src/os2.cpp b/src/os2.cpp
--- a/src/os2.cpp
+++ b/src/os2.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file os2.cpp */
+/** @file os2.cpp OS2 related OS support. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/os_timer.cpp b/src/os_timer.cpp
--- a/src/os_timer.cpp
+++ b/src/os_timer.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file os_timer.cpp */
+/** @file os_timer.cpp OS/compiler dependant real time tick sampling. */
 
 #include "stdafx.h"
 
diff --git a/src/pathfind.cpp b/src/pathfind.cpp
--- a/src/pathfind.cpp
+++ b/src/pathfind.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file pathfind.cpp */
+/** @file pathfind.cpp Implementation of the oldest supported pathfinder. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/pathfind.h b/src/pathfind.h
--- a/src/pathfind.h
+++ b/src/pathfind.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file pathfind.h */
+/** @file pathfind.h The oldest pathfinder that's supported. */
 
 #ifndef PATHFIND_H
 #define PATHFIND_H
diff --git a/src/player_gui.cpp b/src/player_gui.cpp
--- a/src/player_gui.cpp
+++ b/src/player_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file player_gui.cpp */
+/** @file player_gui.cpp Player related GUIs. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/players.cpp b/src/players.cpp
--- a/src/players.cpp
+++ b/src/players.cpp
@@ -1,7 +1,7 @@
 /* $Id$ */
 
-/** @file players.cpp
- */
+/** @file players.cpp Handling of players. */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "engine_func.h"
diff --git a/src/queue.cpp b/src/queue.cpp
--- a/src/queue.cpp
+++ b/src/queue.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file queue.cpp */
+/** @file queue.cpp Implementation of the Queue/Hash. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/queue.h b/src/queue.h
--- a/src/queue.h
+++ b/src/queue.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file queue.h */
+/** @file queue.h Simple Queue/Hash implementations. */
 
 #ifndef QUEUE_H
 #define QUEUE_H
diff --git a/src/rail.cpp b/src/rail.cpp
--- a/src/rail.cpp
+++ b/src/rail.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file rail.cpp */
+/** @file rail.cpp Implementation of rail specific functions. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/rail.h b/src/rail.h
--- a/src/rail.h
+++ b/src/rail.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file rail.h */
+/** @file rail.h Rail specific functions. */
 
 #ifndef RAIL_H
 #define RAIL_H
diff --git a/src/rail_cmd.cpp b/src/rail_cmd.cpp
--- a/src/rail_cmd.cpp
+++ b/src/rail_cmd.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file rail_cmd.cpp */
+/** @file rail_cmd.cpp Handling of rail tiles. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/road.cpp b/src/road.cpp
--- a/src/road.cpp
+++ b/src/road.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file road.cpp Generic road related functions. */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "rail_map.h"
diff --git a/src/road_cmd.cpp b/src/road_cmd.cpp
--- a/src/road_cmd.cpp
+++ b/src/road_cmd.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file road_cmd.cpp */
+/** @file road_cmd.cpp Commands related to road tiles. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/road_cmd.h b/src/road_cmd.h
--- a/src/road_cmd.h
+++ b/src/road_cmd.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file road_cmd.h */
+/** @file road_cmd.h Road related functions. */
 
 #ifndef ROAD_CMD_H
 #define ROAD_CMD_H
diff --git a/src/road_gui.cpp b/src/road_gui.cpp
--- a/src/road_gui.cpp
+++ b/src/road_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file road_gui.cpp */
+/** @file road_gui.cpp GUI for building roads. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/road_map.cpp b/src/road_map.cpp
--- a/src/road_map.cpp
+++ b/src/road_map.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file road_map.cpp */
+/** @file road_map.cpp Complex road accessors. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/road_map.h b/src/road_map.h
--- a/src/road_map.h
+++ b/src/road_map.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file road_map.h */
+/** @file road_map.h Map accessors for roads. */
 
 #ifndef ROAD_MAP_H
 #define ROAD_MAP_H
diff --git a/src/roadveh_cmd.cpp b/src/roadveh_cmd.cpp
--- a/src/roadveh_cmd.cpp
+++ b/src/roadveh_cmd.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file roadveh_cmd.cpp */
+/** @file roadveh_cmd.cpp Handling of road vehicles. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/roadveh_gui.cpp b/src/roadveh_gui.cpp
--- a/src/roadveh_gui.cpp
+++ b/src/roadveh_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file roadveh_gui.cpp */
+/** @file roadveh_gui.cpp GUI for road vehicles. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/saveload.h b/src/saveload.h
--- a/src/saveload.h
+++ b/src/saveload.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file saveload.h */
+/** @file saveload.h Functions/types related to saving and loading games. */
 
 #ifndef SAVELOAD_H
 #define SAVELOAD_H
diff --git a/src/screenshot.cpp b/src/screenshot.cpp
--- a/src/screenshot.cpp
+++ b/src/screenshot.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file screenshot.cpp The creation of screenshots! */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "debug.h"
diff --git a/src/screenshot.h b/src/screenshot.h
--- a/src/screenshot.h
+++ b/src/screenshot.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file screenshot.h */
+/** @file screenshot.h Functions to make screenshots. */
 
 #ifndef SCREENSHOT_H
 #define SCREENSHOT_H
diff --git a/src/sdl.cpp b/src/sdl.cpp
--- a/src/sdl.cpp
+++ b/src/sdl.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file sdl.cpp */
+/** @file sdl.cpp Implementation of SDL support. */
 
 #include "stdafx.h"
 
diff --git a/src/sdl.h b/src/sdl.h
--- a/src/sdl.h
+++ b/src/sdl.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file sdl.h */
+/** @file sdl.h SDL support. */
 
 #ifndef SDL_H
 #define SDL_H
diff --git a/src/settings_gui.cpp b/src/settings_gui.cpp
--- a/src/settings_gui.cpp
+++ b/src/settings_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file settings_gui.cpp */
+/** @file settings_gui.cpp GUI for settings. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/ship.h b/src/ship.h
--- a/src/ship.h
+++ b/src/ship.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file ship.h */
+/** @file ship.h Base for ships. */
 
 #ifndef SHIP_H
 #define SHIP_H
diff --git a/src/ship_cmd.cpp b/src/ship_cmd.cpp
--- a/src/ship_cmd.cpp
+++ b/src/ship_cmd.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file ship_cmd.cpp */
+/** @file ship_cmd.cpp Handling of ships. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/ship_gui.cpp b/src/ship_gui.cpp
--- a/src/ship_gui.cpp
+++ b/src/ship_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file ship_gui.cpp */
+/** @file ship_gui.cpp GUI for ships. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/signs.cpp b/src/signs.cpp
--- a/src/signs.cpp
+++ b/src/signs.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file signs.cpp */
+/** @file signs.cpp Handling of signs. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/signs_gui.cpp b/src/signs_gui.cpp
--- a/src/signs_gui.cpp
+++ b/src/signs_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file signs_gui.cpp */
+/** @file signs_gui.cpp The GUI for signs. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/smallmap_gui.cpp b/src/smallmap_gui.cpp
--- a/src/smallmap_gui.cpp
+++ b/src/smallmap_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file smallmap_gui.cpp */
+/** @file smallmap_gui.cpp GUI that shows a small map of the world with metadata like owner or height. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/sound.cpp b/src/sound.cpp
--- a/src/sound.cpp
+++ b/src/sound.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file sound.cpp */
+/** @file sound.cpp Handling of playing sounds. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/sound/cocoa_s.cpp b/src/sound/cocoa_s.cpp
--- a/src/sound/cocoa_s.cpp
+++ b/src/sound/cocoa_s.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file cocoa_s.cpp Sound driver for cocoa. */
+
 /*****************************************************************************
  *                             Cocoa sound driver                            *
  * Known things left to do:                                                  *
diff --git a/src/sound/cocoa_s.h b/src/sound/cocoa_s.h
--- a/src/sound/cocoa_s.h
+++ b/src/sound/cocoa_s.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file cocoa_s.h Base for Cocoa sound handling. */
+
 #ifndef SOUND_COCOA_H
 #define SOUND_COCOA_H
 
diff --git a/src/sound/null_s.cpp b/src/sound/null_s.cpp
--- a/src/sound/null_s.cpp
+++ b/src/sound/null_s.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file null_s.cpp The sound driver that doesn't produce sound. */
+
 #include "../stdafx.h"
 #include "null_s.h"
 
diff --git a/src/sound/null_s.h b/src/sound/null_s.h
--- a/src/sound/null_s.h
+++ b/src/sound/null_s.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file null_s.h Base for the sound of silence. */
+
 #ifndef SOUND_NULL_H
 #define SOUND_NULL_H
 
diff --git a/src/sound/sdl_s.cpp b/src/sound/sdl_s.cpp
--- a/src/sound/sdl_s.cpp
+++ b/src/sound/sdl_s.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file sdl_s.cpp Playing sound via SDL. */
+
 #ifdef WITH_SDL
 
 #include "../stdafx.h"
diff --git a/src/sound/sdl_s.h b/src/sound/sdl_s.h
--- a/src/sound/sdl_s.h
+++ b/src/sound/sdl_s.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file sdl_s.h Base fo playing sound via SDL. */
+
 #ifndef SOUND_SDL_H
 #define SOUND_SDL_H
 
diff --git a/src/sound/sound_driver.hpp b/src/sound/sound_driver.hpp
--- a/src/sound/sound_driver.hpp
+++ b/src/sound/sound_driver.hpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file sound_driver.hpp Base for all sound drivers. */
+
 #ifndef SOUND_SOUND_DRIVER_HPP
 #define SOUND_SOUND_DRIVER_HPP
 
diff --git a/src/sound/win32_s.cpp b/src/sound/win32_s.cpp
--- a/src/sound/win32_s.cpp
+++ b/src/sound/win32_s.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file win32_s.cpp Handling of sound for Windows. */
+
 #include "../stdafx.h"
 #include "../openttd.h"
 #include "../driver.h"
diff --git a/src/sound/win32_s.h b/src/sound/win32_s.h
--- a/src/sound/win32_s.h
+++ b/src/sound/win32_s.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file win32_s.h Base for Windows sound handling. */
+
 #ifndef SOUND_WIN32_H
 #define SOUND_WIN32_H
 
diff --git a/src/sprite.h b/src/sprite.h
--- a/src/sprite.h
+++ b/src/sprite.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file sprite.h */
+/** @file sprite.h Base for drawing complex sprites. */
 
 #ifndef SPRITE_H
 #define SPRITE_H
diff --git a/src/spritecache.cpp b/src/spritecache.cpp
--- a/src/spritecache.cpp
+++ b/src/spritecache.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file spritecache.cpp */
+/** @file spritecache.cpp Caching of sprites. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/spritecache.h b/src/spritecache.h
--- a/src/spritecache.h
+++ b/src/spritecache.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file spritecache.h */
+/** @file spritecache.h Functions to cache sprites in memory. */
 
 #ifndef SPRITECACHE_H
 #define SPRITECACHE_H
diff --git a/src/spriteloader/grf.cpp b/src/spriteloader/grf.cpp
--- a/src/spriteloader/grf.cpp
+++ b/src/spriteloader/grf.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file grf.cpp */
+/** @file grf.cpp Reading graphics data from (New)GRF files. */
 
 #include "../stdafx.h"
 #include "../gfx_func.h"
diff --git a/src/spriteloader/grf.hpp b/src/spriteloader/grf.hpp
--- a/src/spriteloader/grf.hpp
+++ b/src/spriteloader/grf.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file grf.hpp */
+/** @file grf.hpp Base for reading sprites from (New)GRFs. */
 
 #ifndef SPRITELOADER_GRF_HPP
 #define SPRITELOADER_GRF_HPP
diff --git a/src/spriteloader/png.cpp b/src/spriteloader/png.cpp
--- a/src/spriteloader/png.cpp
+++ b/src/spriteloader/png.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file png.cpp */
+/** @file png.cpp Reading sprites from png files. */
 
 #ifdef WITH_PNG
 
diff --git a/src/spriteloader/png.hpp b/src/spriteloader/png.hpp
--- a/src/spriteloader/png.hpp
+++ b/src/spriteloader/png.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file png.hpp */
+/** @file png.hpp Base for reading files from PNG. */
 
 #ifndef SPRITELOADER_PNG_HPP
 #define SPRITELOADER_PNG_HPP
diff --git a/src/spriteloader/spriteloader.hpp b/src/spriteloader/spriteloader.hpp
--- a/src/spriteloader/spriteloader.hpp
+++ b/src/spriteloader/spriteloader.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file spriteloader.hpp */
+/** @file spriteloader.hpp Base for loading sprites. */
 
 #ifndef SPRITELOADER_HPP
 #define SPRITELOADER_HPP
diff --git a/src/station.cpp b/src/station.cpp
--- a/src/station.cpp
+++ b/src/station.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file station.cpp */
+/** @file station.cpp Implementation of the station base class. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/station_cmd.cpp b/src/station_cmd.cpp
--- a/src/station_cmd.cpp
+++ b/src/station_cmd.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file station_cmd.cpp */
+/** @file station_cmd.cpp Handling of station tiles. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/station_gui.cpp b/src/station_gui.cpp
--- a/src/station_gui.cpp
+++ b/src/station_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file station_gui.cpp */
+/** @file station_gui.cpp The GUI for stations. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/station_map.h b/src/station_map.h
--- a/src/station_map.h
+++ b/src/station_map.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file station_map.h */
+/** @file station_map.h Maps accessors for stations. */
 
 #ifndef STATION_MAP_H
 #define STATION_MAP_H
diff --git a/src/statusbar_gui.cpp b/src/statusbar_gui.cpp
--- a/src/statusbar_gui.cpp
+++ b/src/statusbar_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file main_gui.cpp */
+/** @file statusbar_gui.cpp The GUI for the bottom status bar. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/stdafx.h b/src/stdafx.h
--- a/src/stdafx.h
+++ b/src/stdafx.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file stdafx.h */
+/** @file stdafx.h Definition of base types and functions in a cross-platform compatible way. */
 
 #ifndef STDAFX_H
 #define STDAFX_H
diff --git a/src/strgen/strgen.cpp b/src/strgen/strgen.cpp
--- a/src/strgen/strgen.cpp
+++ b/src/strgen/strgen.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file strgen.cpp Tool to create computer readable (stand-alone) translation files. */
+
 #include "../stdafx.h"
 #include "../core/alloc_func.hpp"
 #include "../core/endian_func.hpp"
diff --git a/src/string.cpp b/src/string.cpp
--- a/src/string.cpp
+++ b/src/string.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file string.cpp */
+/** @file string.cpp Handling of C-type strings (char*). */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/strings.cpp b/src/strings.cpp
--- a/src/strings.cpp
+++ b/src/strings.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file strings.cpp */
+/** @file strings.cpp Handling of translated strings. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/subsidy_gui.cpp b/src/subsidy_gui.cpp
--- a/src/subsidy_gui.cpp
+++ b/src/subsidy_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file subsidy_gui.cpp */
+/** @file subsidy_gui.cpp GUI for subsidies. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/table/ai_rail.h b/src/table/ai_rail.h
--- a/src/table/ai_rail.h
+++ b/src/table/ai_rail.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file ai_rail.h Tables that the default AI uses to build tracks/stations. */
+
 struct AiDefaultBlockData {
 	byte mode;
 	DiagDirection attr;
diff --git a/src/table/autorail.h b/src/table/autorail.h
--- a/src/table/autorail.h
+++ b/src/table/autorail.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file autorail.h Highlight/sprite information for autorail. */
+
 /* Rail selection types (directions):
  *  / \    / \    / \    / \   / \   / \
  * /  /\  /\  \  /===\  /   \ /|  \ /  |\
diff --git a/src/table/build_industry.h b/src/table/build_industry.h
--- a/src/table/build_industry.h
+++ b/src/table/build_industry.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file build_industry.h */
+/** @file build_industry.h Tables with default industry layouts and behaviours. */
 
 #ifndef BUILD_INDUSTRY_H
 #define BUILD_INDUSTRY_H
diff --git a/src/table/cargo_const.h b/src/table/cargo_const.h
--- a/src/table/cargo_const.h
+++ b/src/table/cargo_const.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/* Table of all default cargo types */
+/** @file cargo_const.h Table of all default cargo types */
 
 #define MK(bt, label, c, e, f, g, h, fr, te, ks1, ks2, ks3, ks4, ks5, l, m) \
           {bt, label, 0, c, c, e, f, {g, h}, fr, te, 0, 0, ks1, ks2, ks3, ks4, ks5, l, m, NULL}
diff --git a/src/table/clear_land.h b/src/table/clear_land.h
--- a/src/table/clear_land.h
+++ b/src/table/clear_land.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file clear_land.h Tables with sprites for clear land and fences. */
+
 static const SpriteID _landscape_clear_sprites[8] = {
 	0xFA0,
 	0xFB3,
diff --git a/src/table/control_codes.h b/src/table/control_codes.h
--- a/src/table/control_codes.h
+++ b/src/table/control_codes.h
@@ -1,11 +1,14 @@
 /* $Id$ */
 
+/** @file control_codes.h Control codes that are embedded in the translation strings. */
+
 #ifndef CONTROL_CODES_H
 #define CONTROL_CODES_H
 
-/* List of string control codes used for string formatting, displaying, and
- * by strgen to generate the language files. */
-
+/**
+ * List of string control codes used for string formatting, displaying, and
+ * by strgen to generate the language files.
+ */
 enum StringControlCode {
 	SCC_CONTROL_START = 0xE000,
 	SCC_CONTROL_END   = 0xE1FF,
diff --git a/src/table/elrail_data.h b/src/table/elrail_data.h
--- a/src/table/elrail_data.h
+++ b/src/table/elrail_data.h
@@ -1,4 +1,5 @@
 /* $Id$ */
+
 /** @file elrail_data.h Stores all the data for overhead wire and pylon drawing.
  *  @see elrail.c */
 
diff --git a/src/table/engines.h b/src/table/engines.h
--- a/src/table/engines.h
+++ b/src/table/engines.h
@@ -1,12 +1,12 @@
 /* $Id$ */
 
-#ifndef ENGINES_H
-#define ENGINES_H
-
 /** @file table/engines.h
  *  This file contains all the data for vehicles
  */
 
+#ifndef ENGINES_H
+#define ENGINES_H
+
 enum {
 	RC_W = 0xFF, ///< Running cost price index (out of range) of wagons
 	RC_S = 0x2A, ///< Running cost price index of steam
diff --git a/src/table/files.h b/src/table/files.h
--- a/src/table/files.h
+++ b/src/table/files.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file files.h MD5 checksum information and names of the original and extra data files. */
+
 /*
 	MD5 sums of graphics files
 
diff --git a/src/table/genland.h b/src/table/genland.h
--- a/src/table/genland.h
+++ b/src/table/genland.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file genland.h Table used to generate deserts and/or rain forests. */
+
 #define M(x, y) {x,  y}
 
 static const TileIndexDiffC _make_desert_or_rainforest_data[] = {
diff --git a/src/table/industry_land.h b/src/table/industry_land.h
--- a/src/table/industry_land.h
+++ b/src/table/industry_land.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file industry_land.h */
+/** @file industry_land.h Information about the behaviour of the default industry tiles. */
 
 /**
  * This is used to gather some data about animation
diff --git a/src/table/landscape_sprite.h b/src/table/landscape_sprite.h
--- a/src/table/landscape_sprite.h
+++ b/src/table/landscape_sprite.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file landscape_sprite.h Offsets of sprites to replace for non-temperate landscapes. */
+
 enum {
 	END  = 0xFFFF
 };
diff --git a/src/table/palettes.h b/src/table/palettes.h
--- a/src/table/palettes.h
+++ b/src/table/palettes.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file palettes.h The colour translation of the GRF palettes. */
+
 #define M(r, g, b) { r, g, b }
 static const Colour _palettes[][256] = {
 	/* palette 1 (TTD Windows) */
diff --git a/src/table/road_land.h b/src/table/road_land.h
--- a/src/table/road_land.h
+++ b/src/table/road_land.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file road_land.h Sprite constructs for road depots. */
+
 #define TILE_SEQ_LINE(img, pal, dx, dy, sx, sy) { dx, dy, 0, sx, sy, 20, {img, pal} },
 #define TILE_SEQ_END() { 0, 0, 0, 0, 0, 0, {0, 0} }
 
diff --git a/src/table/sprites.h b/src/table/sprites.h
--- a/src/table/sprites.h
+++ b/src/table/sprites.h
@@ -1,8 +1,5 @@
 /* $Id$ */
 
-#ifndef SPRITES_H
-#define SPRITES_H
-
 /** @file sprites.h
  * This file contails all sprite-related enums and defines. These consist mainly of
  * the sprite numbers and a bunch of masks and macros to handle sprites and to get
@@ -32,6 +29,9 @@
  * @todo Split the "Sprites" enum into smaller chunks and document them
  */
 
+#ifndef SPRITES_H
+#define SPRITES_H
+
 #include "../gfx_type.h"
 
 enum Sprites {
diff --git a/src/table/station_land.h b/src/table/station_land.h
--- a/src/table/station_land.h
+++ b/src/table/station_land.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file station_land.h Sprites to use and how to display them for station tiles. */
+
 #define TILE_SEQ_LINE(dx, dy, dz, sx, sy, sz, img) { dx, dy, dz, sx, sy, sz, {img, PAL_NONE} },
 #define TILE_SEQ_LINE_PAL(dx, dy, dz, sx, sy, sz, img, pal) { dx, dy, dz, sx, sy, sz, {img, pal} },
 #define TILE_SEQ_END() { (byte)0x80, 0, 0, 0, 0, 0, {0, 0} }
diff --git a/src/table/town_land.h b/src/table/town_land.h
--- a/src/table/town_land.h
+++ b/src/table/town_land.h
@@ -1,7 +1,6 @@
 /* $Id$ */
 
-/** @file town_land.h */
-
+/** @file town_land.h Sprites to use and how to display them for town tiles. */
 
 /** Writes the data into the Town Tile Drawing Struct
  * @param s1 The first sprite of the building, mostly the ground sprite
diff --git a/src/table/track_land.h b/src/table/track_land.h
--- a/src/table/track_land.h
+++ b/src/table/track_land.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file track_land.h Sprites to use and how to display them for train depot/waypoint tiles. */
+
 #define TILE_SEQ_LINE(img, dx, dy, sx, sy) { dx, dy, 0, sx, sy, 23, {img, PAL_NONE} },
 #define TILE_SEQ_END() { (byte)0x80, 0, 0, 0, 0, 0, {0, 0} }
 
diff --git a/src/table/train_cmd.h b/src/table/train_cmd.h
--- a/src/table/train_cmd.h
+++ b/src/table/train_cmd.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file train_cmd.h Sprites to use for trains. */
+
 static const SpriteID _engine_sprite_base[] = {
 0x0B59, 0x0B61, 0x0B69, 0x0BE1, 0x0B71, 0x0B75, 0x0B7D, 0x0B7D,
 0x0B85, 0x0B85, 0x0B8D, 0x0B8D, 0x0BC9, 0x0BD1, 0x0BD9, 0x0BE9,
diff --git a/src/table/tree_land.h b/src/table/tree_land.h
--- a/src/table/tree_land.h
+++ b/src/table/tree_land.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file tree_land.h Sprites to use and how to display them for tree tiles. */
+
 #ifndef TREE_LAND_H
 #define TREE_LAND_H
 
diff --git a/src/table/unicode.h b/src/table/unicode.h
--- a/src/table/unicode.h
+++ b/src/table/unicode.h
@@ -1,5 +1,6 @@
 /* $Id$ */
 
+/** @file unicode.h Character mapping for using Unicode characters in OTTD. */
 
 struct DefaultUnicodeMapping {
 	WChar code; ///< Unicode value
diff --git a/src/table/unmovable_land.h b/src/table/unmovable_land.h
--- a/src/table/unmovable_land.h
+++ b/src/table/unmovable_land.h
@@ -1,5 +1,6 @@
 /* $Id$ */
 
+/** @file unmovable_land.h Sprites to use and how to display them for unmovable tiles. */
 
 static const DrawTileSeqStruct _draw_tile_transmitterlighthouse_data[] = {
 	{   7,  7,  0,  2,  2, 70, {SPR_UNMOVABLE_TRANSMITTER, PAL_NONE}},
diff --git a/src/table/water_land.h b/src/table/water_land.h
--- a/src/table/water_land.h
+++ b/src/table/water_land.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file water_land.h Sprites to use and how to display them for water tiles (depots/shiplifts). */
+
 struct WaterDrawTileStruct {
 	byte delta_x;
 	byte delta_y;
diff --git a/src/terraform_gui.cpp b/src/terraform_gui.cpp
--- a/src/terraform_gui.cpp
+++ b/src/terraform_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file terraform_gui.cpp */
+/** @file terraform_gui.cpp GUI related to terraforming the map. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/texteff.cpp b/src/texteff.cpp
--- a/src/texteff.cpp
+++ b/src/texteff.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file texteff.cpp */
+/** @file texteff.cpp Handling of text effects. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/texteff.hpp b/src/texteff.hpp
--- a/src/texteff.hpp
+++ b/src/texteff.hpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file texteff.hpp Functions related to text effects. */
+
 #ifndef TEXTEFF_HPP
 #define TEXTEFF_HPP
 
diff --git a/src/tgp.h b/src/tgp.h
--- a/src/tgp.h
+++ b/src/tgp.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file tgp.h */
+/** @file tgp.h Functions for the Perlin noise enhanced map generator. */
 
 #ifndef TGP_H
 #define TGP_H
diff --git a/src/thread.h b/src/thread.h
--- a/src/thread.h
+++ b/src/thread.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file thread.h */
+/** @file thread.h Base of all threads. */
 
 #ifndef THREAD_H
 #define THREAD_H
diff --git a/src/tile_map.cpp b/src/tile_map.cpp
--- a/src/tile_map.cpp
+++ b/src/tile_map.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file tile_map.cpp */
+/** @file tile_map.cpp Global tile accessors. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/timetable.h b/src/timetable.h
--- a/src/timetable.h
+++ b/src/timetable.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file timetable.h */
+/** @file timetable.h Functions related to time tabling. */
 
 #ifndef TIMETABLE_H
 #define TIMETABLE_H
diff --git a/src/timetable_cmd.cpp b/src/timetable_cmd.cpp
--- a/src/timetable_cmd.cpp
+++ b/src/timetable_cmd.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file timetable_cmd.cpp */
+/** @file timetable_cmd.cpp Commands related to time tabling. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/timetable_gui.cpp b/src/timetable_gui.cpp
--- a/src/timetable_gui.cpp
+++ b/src/timetable_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file timetable_gui.cpp */
+/** @file timetable_gui.cpp GUI for time tabling. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/town.h b/src/town.h
--- a/src/town.h
+++ b/src/town.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file town.h */
+/** @file town.h Base of the town class. */
 
 #ifndef TOWN_H
 #define TOWN_H
diff --git a/src/town_cmd.cpp b/src/town_cmd.cpp
--- a/src/town_cmd.cpp
+++ b/src/town_cmd.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file town_cmd.cpp */
+/** @file town_cmd.cpp Handling of town tiles. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/town_gui.cpp b/src/town_gui.cpp
--- a/src/town_gui.cpp
+++ b/src/town_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file town_gui.cpp */
+/** @file town_gui.cpp GUI for towns. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/train.h b/src/train.h
--- a/src/train.h
+++ b/src/train.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file train.h */
+/** @file train.h Base for the train class. */
 
 #ifndef TRAIN_H
 #define TRAIN_H
diff --git a/src/train_cmd.cpp b/src/train_cmd.cpp
--- a/src/train_cmd.cpp
+++ b/src/train_cmd.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file train_cmd.cpp */
+/** @file train_cmd.cpp Handling of trains. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/train_gui.cpp b/src/train_gui.cpp
--- a/src/train_gui.cpp
+++ b/src/train_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file train_gui.cpp */
+/** @file train_gui.cpp GUI for trains. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/transparency.h b/src/transparency.h
--- a/src/transparency.h
+++ b/src/transparency.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file transparency.h */
+/** @file transparency.h Functions related to transparency. */
 
 #ifndef TRANSPARENCY_H
 #define TRANSPARENCY_H
diff --git a/src/transparency_gui.cpp b/src/transparency_gui.cpp
--- a/src/transparency_gui.cpp
+++ b/src/transparency_gui.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file transparency_gui.cpp The transparency GUI. */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "gui.h"
diff --git a/src/transparency_gui.h b/src/transparency_gui.h
--- a/src/transparency_gui.h
+++ b/src/transparency_gui.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file transparency_gui.h GUI functions related to transparency. */
+
 #ifndef TRANSPARENCY_GUI_H
 #define TRANSPARENCY_GUI_H
 
diff --git a/src/tree_cmd.cpp b/src/tree_cmd.cpp
--- a/src/tree_cmd.cpp
+++ b/src/tree_cmd.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file tree_cmd.cpp */
+/** @file tree_cmd.cpp Handling of tree tiles. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/tree_map.h b/src/tree_map.h
--- a/src/tree_map.h
+++ b/src/tree_map.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file tree_map.h */
+/** @file tree_map.h Map accessors for tree tiles. */
 
 #ifndef TREE_MAP_H
 #define TREE_MAP_H
diff --git a/src/tunnel_map.cpp b/src/tunnel_map.cpp
--- a/src/tunnel_map.cpp
+++ b/src/tunnel_map.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file tunnel_map.cpp */
+/** @file tunnel_map.cpp Map accessors for tunnels. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/tunnel_map.h b/src/tunnel_map.h
--- a/src/tunnel_map.h
+++ b/src/tunnel_map.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file tunnel_map.h */
+/** @file tunnel_map.h Map accessors for tunnels. */
 
 #ifndef TUNNEL_MAP_H
 #define TUNNEL_MAP_H
diff --git a/src/unix.cpp b/src/unix.cpp
--- a/src/unix.cpp
+++ b/src/unix.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file unix.cpp */
+/** @file unix.cpp Implementation of Unix specific file handling. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/unmovable.h b/src/unmovable.h
--- a/src/unmovable.h
+++ b/src/unmovable.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file unmovable.h */
+/** @file unmovable.h Functions related to unmovable objects. */
 
 #ifndef UNMOVABLE_H
 #define UNMOVABLE_H
diff --git a/src/unmovable_cmd.cpp b/src/unmovable_cmd.cpp
--- a/src/unmovable_cmd.cpp
+++ b/src/unmovable_cmd.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file unmovable_cmd.cpp */
+/** @file unmovable_cmd.cpp Handling of unmovable tiles. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/unmovable_map.h b/src/unmovable_map.h
--- a/src/unmovable_map.h
+++ b/src/unmovable_map.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file unmovable_map.h */
+/** @file unmovable_map.h Map accessors for unmovable tiles. */
 
 #ifndef UNMOVABLE_MAP_H
 #define UNMOVABLE_MAP_H
diff --git a/src/variables.h b/src/variables.h
--- a/src/variables.h
+++ b/src/variables.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file variables.h */
+/** @file variables.h Messing file that will cease to exist some time in the future. */
 
 #ifndef VARIABLES_H
 #define VARIABLES_H
diff --git a/src/vehicle.cpp b/src/vehicle.cpp
--- a/src/vehicle.cpp
+++ b/src/vehicle.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file vehicle.cpp */
+/** @file vehicle.cpp Base implementations of all vehicles. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/vehicle_func.h b/src/vehicle_func.h
--- a/src/vehicle_func.h
+++ b/src/vehicle_func.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file vehicle.h Functions related to vehicles. */
+/** @file vehicle_func.h Functions related to vehicles. */
 
 #ifndef VEHICLE_FUNC_H
 #define VEHICLE_FUNC_H
diff --git a/src/vehicle_gui.cpp b/src/vehicle_gui.cpp
--- a/src/vehicle_gui.cpp
+++ b/src/vehicle_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file vehicle_gui.cpp */
+/** @file vehicle_gui.cpp The base GUI for all vehicles. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/vehicle_gui.h b/src/vehicle_gui.h
--- a/src/vehicle_gui.h
+++ b/src/vehicle_gui.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file vehicle_gui.h */
+/** @file vehicle_gui.h Functions related to the vehicle's GUIs. */
 
 #ifndef VEHICLE_GUI_H
 #define VEHICLE_GUI_H
diff --git a/src/video/cocoa/cocoa_keys.h b/src/video/cocoa/cocoa_keys.h
--- a/src/video/cocoa/cocoa_keys.h
+++ b/src/video/cocoa/cocoa_keys.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file cocoa_keys.h Mappings of Cocoa keys. */
+
 #ifndef COCOA_KEYS_H
 #define COCOA_KEYS_H
 
diff --git a/src/video/cocoa/cocoa_v.h b/src/video/cocoa/cocoa_v.h
--- a/src/video/cocoa/cocoa_v.h
+++ b/src/video/cocoa/cocoa_v.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file cocoa_v.h The Cocoa video driver. */
+
 #ifndef VIDEO_COCOA_H
 #define VIDEO_COCOA_H
 
diff --git a/src/video/dedicated_v.cpp b/src/video/dedicated_v.cpp
--- a/src/video/dedicated_v.cpp
+++ b/src/video/dedicated_v.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file dedicated_v.cpp Dedicated server video 'driver'. */
+
 #include "../stdafx.h"
 
 #ifdef ENABLE_NETWORK
diff --git a/src/video/dedicated_v.h b/src/video/dedicated_v.h
--- a/src/video/dedicated_v.h
+++ b/src/video/dedicated_v.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file dedicated_v.h Base for the dedicated video driver. */
+
 #ifndef VIDEO_DEDICATED_H
 #define VIDEO_DEDICATED_H
 
diff --git a/src/video/null_v.cpp b/src/video/null_v.cpp
--- a/src/video/null_v.cpp
+++ b/src/video/null_v.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file null_v.cpp The videio driver that doesn't blit. */
+
 #include "../stdafx.h"
 #include "../openttd.h"
 #include "../gfx_func.h"
diff --git a/src/video/null_v.h b/src/video/null_v.h
--- a/src/video/null_v.h
+++ b/src/video/null_v.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file null_v.h Base of the video driver that doesn't blit. */
+
 #ifndef VIDEO_NULL_H
 #define VIDEO_NULL_H
 
diff --git a/src/video/sdl_v.cpp b/src/video/sdl_v.cpp
--- a/src/video/sdl_v.cpp
+++ b/src/video/sdl_v.cpp
@@ -1,9 +1,10 @@
 /* $Id$ */
 
-#include "../stdafx.h"
+/** @file sdl_v.cpp Implementation of the SDL video driver. */
 
 #ifdef WITH_SDL
 
+#include "../stdafx.h"
 #include "../openttd.h"
 #include "../debug.h"
 #include "../gfx_func.h"
diff --git a/src/video/sdl_v.h b/src/video/sdl_v.h
--- a/src/video/sdl_v.h
+++ b/src/video/sdl_v.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file sdl_v.h Base of the SDL video driver. */
+
 #ifndef VIDEO_SDL_H
 #define VIDEO_SDL_H
 
diff --git a/src/video/video_driver.hpp b/src/video/video_driver.hpp
--- a/src/video/video_driver.hpp
+++ b/src/video/video_driver.hpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file video_driver.hpp Base of all video drivers. */
+
 #ifndef VIDEO_VIDEO_DRIVER_HPP
 #define VIDEO_VIDEO_DRIVER_HPP
 
diff --git a/src/video/win32_v.cpp b/src/video/win32_v.cpp
--- a/src/video/win32_v.cpp
+++ b/src/video/win32_v.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file win32_v.cpp Implementation of the Windows (GDI) video driver. */
+
 #include "../stdafx.h"
 #include "../openttd.h"
 #include "../gfx_func.h"
diff --git a/src/video/win32_v.h b/src/video/win32_v.h
--- a/src/video/win32_v.h
+++ b/src/video/win32_v.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file win32_v.h Base of the Windows video driver. */
+
 #ifndef VIDEO_WIN32_H
 #define VIDEO_WIN32_H
 
diff --git a/src/viewport.cpp b/src/viewport.cpp
--- a/src/viewport.cpp
+++ b/src/viewport.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file viewport.cpp
+/** @file viewport.cpp Handling of all viewports.
  *
  * \verbatim
  * The in-game coordinate system looks like this *
diff --git a/src/void_map.h b/src/void_map.h
--- a/src/void_map.h
+++ b/src/void_map.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file void_map.h */
+/** @file void_map.h Map accessors for void tiles. */
 
 #ifndef VOID_MAP_H
 #define VOID_MAP_H
diff --git a/src/water_cmd.cpp b/src/water_cmd.cpp
--- a/src/water_cmd.cpp
+++ b/src/water_cmd.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file water_cmd.cpp */
+/** @file water_cmd.cpp Handling of water tiles. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/water_map.h b/src/water_map.h
--- a/src/water_map.h
+++ b/src/water_map.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file water_map.h */
+/** @file water_map.h Map accessors for water tiles. */
 
 #ifndef WATER_MAP_H
 #define WATER_MAP_H
diff --git a/src/waypoint.cpp b/src/waypoint.cpp
--- a/src/waypoint.cpp
+++ b/src/waypoint.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file waypoint.cpp */
+/** @file waypoint.cpp Handling of waypoints. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/waypoint.h b/src/waypoint.h
--- a/src/waypoint.h
+++ b/src/waypoint.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file waypoint.h */
+/** @file waypoint.h Base of waypoints. */
 
 #ifndef WAYPOINT_H
 #define WAYPOINT_H
diff --git a/src/widget.cpp b/src/widget.cpp
--- a/src/widget.cpp
+++ b/src/widget.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file widget.cpp */
+/** @file widget.cpp Handling of the default/simple widgets. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/widgets/dropdown.cpp b/src/widgets/dropdown.cpp
--- a/src/widgets/dropdown.cpp
+++ b/src/widgets/dropdown.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file dropdown.cpp Implementation of the dropdown widget. */
+
 #include "../stdafx.h"
 #include "../openttd.h"
 #include "../strings_type.h"
diff --git a/src/widgets/dropdown_func.h b/src/widgets/dropdown_func.h
--- a/src/widgets/dropdown_func.h
+++ b/src/widgets/dropdown_func.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file dropdown_func.h Functions related to the drop down widget. */
+
 #ifndef WIDGETS_DROPDOWN_FUNC_H
 #define WIDGETS_DROPDOWN_FUNC_H
 
diff --git a/src/widgets/dropdown_type.h b/src/widgets/dropdown_type.h
--- a/src/widgets/dropdown_type.h
+++ b/src/widgets/dropdown_type.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file dropdown_type.h Types related to the drop down widget. */
+
 #ifndef WIDGETS_DROPDOWN_TYPE_H
 #define WIDGETS_DROPDOWN_TYPE_H
 
diff --git a/src/window.cpp b/src/window.cpp
--- a/src/window.cpp
+++ b/src/window.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file window.cpp windowing system, widgets and events */
+/** @file window.cpp Windowing system, widgets and events */
 
 #include "stdafx.h"
 #include <stdarg.h>
diff --git a/src/yapf/nodelist.hpp b/src/yapf/nodelist.hpp
--- a/src/yapf/nodelist.hpp
+++ b/src/yapf/nodelist.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file nodelist.hpp */
+/** @file nodelist.hpp List of nodes used for the A-star pathfinder. */
 
 #ifndef  NODELIST_HPP
 #define  NODELIST_HPP
diff --git a/src/yapf/yapf.h b/src/yapf/yapf.h
--- a/src/yapf/yapf.h
+++ b/src/yapf/yapf.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file yapf.h */
+/** @file yapf.h Entry point for OpenTTD to YAPF. */
 
 #ifndef  YAPF_H
 #define  YAPF_H
diff --git a/src/yapf/yapf.hpp b/src/yapf/yapf.hpp
--- a/src/yapf/yapf.hpp
+++ b/src/yapf/yapf.hpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file yapf.hpp Base includes/functions for YAPF. */
+
 #ifndef  YAPF_HPP
 #define  YAPF_HPP
 
diff --git a/src/yapf/yapf_base.hpp b/src/yapf/yapf_base.hpp
--- a/src/yapf/yapf_base.hpp
+++ b/src/yapf/yapf_base.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file yapf_base.hpp */
+/** @file yapf_base.hpp Base classes for YAPF. */
 
 #ifndef  YAPF_BASE_HPP
 #define  YAPF_BASE_HPP
diff --git a/src/yapf/yapf_common.hpp b/src/yapf/yapf_common.hpp
--- a/src/yapf/yapf_common.hpp
+++ b/src/yapf/yapf_common.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file yapf_common.hpp */
+/** @file yapf_common.hpp Commonly used classes for YAPF. */
 
 #ifndef  YAPF_COMMON_HPP
 #define  YAPF_COMMON_HPP
diff --git a/src/yapf/yapf_costbase.hpp b/src/yapf/yapf_costbase.hpp
--- a/src/yapf/yapf_costbase.hpp
+++ b/src/yapf/yapf_costbase.hpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file yapf_costbase.hpp Handling of cost determination. */
+
 #ifndef  YAPF_COSTBASE_HPP
 #define  YAPF_COSTBASE_HPP
 
diff --git a/src/yapf/yapf_costcache.hpp b/src/yapf/yapf_costcache.hpp
--- a/src/yapf/yapf_costcache.hpp
+++ b/src/yapf/yapf_costcache.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file yapf_costcache.hpp */
+/** @file yapf_costcache.hpp Caching of segment costs. */
 
 #ifndef  YAPF_COSTCACHE_HPP
 #define  YAPF_COSTCACHE_HPP
diff --git a/src/yapf/yapf_costrail.hpp b/src/yapf/yapf_costrail.hpp
--- a/src/yapf/yapf_costrail.hpp
+++ b/src/yapf/yapf_costrail.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file yapf_costrail.hpp */
+/** @file yapf_costrail.hpp Cost determination for rails. */
 
 #ifndef  YAPF_COSTRAIL_HPP
 #define  YAPF_COSTRAIL_HPP
diff --git a/src/yapf/yapf_destrail.hpp b/src/yapf/yapf_destrail.hpp
--- a/src/yapf/yapf_destrail.hpp
+++ b/src/yapf/yapf_destrail.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file yapf_destrail.hpp */
+/** @file yapf_destrail.hpp Determining the destination for rail vehicles. */
 
 #ifndef  YAPF_DESTRAIL_HPP
 #define  YAPF_DESTRAIL_HPP
diff --git a/src/yapf/yapf_node.hpp b/src/yapf/yapf_node.hpp
--- a/src/yapf/yapf_node.hpp
+++ b/src/yapf/yapf_node.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file yapf_node.hpp */
+/** @file yapf_node.hpp Node in the pathfinder's graph. */
 
 #ifndef  YAPF_NODE_HPP
 #define  YAPF_NODE_HPP
diff --git a/src/yapf/yapf_node_rail.hpp b/src/yapf/yapf_node_rail.hpp
--- a/src/yapf/yapf_node_rail.hpp
+++ b/src/yapf/yapf_node_rail.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file yapf_node_rail.hpp */
+/** @file yapf_node_rail.hpp Node tailored for rail pathfinding. */
 
 #ifndef  YAPF_NODE_RAIL_HPP
 #define  YAPF_NODE_RAIL_HPP
diff --git a/src/yapf/yapf_node_road.hpp b/src/yapf/yapf_node_road.hpp
--- a/src/yapf/yapf_node_road.hpp
+++ b/src/yapf/yapf_node_road.hpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file yapf_node_road.hpp */
+/** @file yapf_node_road.hpp Node tailored for road pathfinding. */
 
 #ifndef  YAPF_NODE_ROAD_HPP
 #define  YAPF_NODE_ROAD_HPP
diff --git a/src/yapf/yapf_rail.cpp b/src/yapf/yapf_rail.cpp
--- a/src/yapf/yapf_rail.cpp
+++ b/src/yapf/yapf_rail.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file yapf_rail.cpp */
+/** @file yapf_rail.cpp The rail pathfinding. */
 
 #include "../stdafx.h"
 
diff --git a/src/yapf/yapf_road.cpp b/src/yapf/yapf_road.cpp
--- a/src/yapf/yapf_road.cpp
+++ b/src/yapf/yapf_road.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file yapf_road.cpp */
+/** @file yapf_road.cpp The road pathfinding. */
 
 #include "../stdafx.h"
 #include "../depot_base.h"
diff --git a/src/yapf/yapf_settings.h b/src/yapf/yapf_settings.h
--- a/src/yapf/yapf_settings.h
+++ b/src/yapf/yapf_settings.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file yapf_settings.h */
+/** @file yapf_settings.h Penalty settings for YAPF. */
 
 #if !defined(YAPF_SETTINGS_H) || defined(YS_DEF)
 
diff --git a/src/yapf/yapf_ship.cpp b/src/yapf/yapf_ship.cpp
--- a/src/yapf/yapf_ship.cpp
+++ b/src/yapf/yapf_ship.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file yapf_ship.cpp */
+/** @file yapf_ship.cpp Implementation of YAPF for ships. */
 
 #include "../stdafx.h"
 
diff --git a/src/zoom_func.h b/src/zoom_func.h
--- a/src/zoom_func.h
+++ b/src/zoom_func.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file zoom_func.h */
+/** @file zoom_func.h Functions related to zooming. */
 
 #ifndef ZOOM_FUNC_H
 #define ZOOM_FUNC_H