(svn r14461) -Document: add some doxygen comments (Albert)

8 files changed, 60 insertions, 12 deletions

diff --git a/src/gfx_type.h b/src/gfx_type.h
index 039191a75..558519fb0 100644
--- a/src/gfx_type.h
+++ b/src/gfx_type.h
@@ -12,9 +12,10 @@
 
 typedef uint32 SpriteID;      ///< The number of a sprite, without mapping bits and colortables
 
+/** Combination of a palette sprite and a 'real' sprite */
 struct PalSpriteID {
-	SpriteID sprite;
-	SpriteID pal;
+	SpriteID sprite;  ///< The 'real' sprite
+	SpriteID pal;     ///< The palette (use \c PAL_NONE) if not needed)
 };
 typedef int32 CursorID;
 
diff --git a/src/landscape.cpp b/src/landscape.cpp
index 2e4e10c47..2277bdff0 100644
--- a/src/landscape.cpp
+++ b/src/landscape.cpp
@@ -67,7 +67,7 @@ const byte _tileh_to_sprite[32] = {
 SnowLine *_snow_line = NULL;
 
 /**
- * Applys a foundation to a slope.
+ * Applies a foundation to a slope.
  *
  * @pre      Foundation and slope must be valid combined.
  * @param f  The #Foundation.
@@ -473,6 +473,12 @@ TrackStatus GetTileTrackStatus(TileIndex tile, TransportType mode, uint sub_mode
 	return _tile_type_procs[GetTileType(tile)]->get_tile_track_status_proc(tile, mode, sub_mode, side);
 }
 
+/**
+ * Change the owner of a tile
+ * @param tile      Tile to change
+ * @param old_owner Current owner of the tile
+ * @param new_owner New owner of the tile
+ */
 void ChangeTileOwner(TileIndex tile, Owner old_owner, Owner new_owner)
 {
 	_tile_type_procs[GetTileType(tile)]->change_tile_owner_proc(tile, old_owner, new_owner);
diff --git a/src/landscape_type.h b/src/landscape_type.h
index eb6b9e7a6..f1955f4d3 100644
--- a/src/landscape_type.h
+++ b/src/landscape_type.h
@@ -5,10 +5,10 @@
 #ifndef LANDSCAPE_TYPE_H
 #define LANDSCAPE_TYPE_H
 
-typedef byte LandscapeID;
+typedef byte LandscapeID; ///< Landscape type. @see LandscapeType
 
-/* Landscape types */
-enum {
+/** Landscape types */
+enum LandscapeType {
 	LT_TEMPERATE  = 0,
 	LT_ARCTIC     = 1,
 	LT_TROPIC     = 2,
diff --git a/src/sprite.h b/src/sprite.h
index 2b1755432..2fbef0c64 100644
--- a/src/sprite.h
+++ b/src/sprite.h
@@ -23,8 +23,9 @@
  * bounding box. Used especially for various multi-sprite buildings (like
  * depots or stations): */
 
+/** A tile child sprite and palette to draw for stations etc, with 3D bounding box */
 struct DrawTileSeqStruct {
-	int8 delta_x; // 0x80 is sequence terminator
+	int8 delta_x; ///< \c 0x80 is sequence terminator
 	int8 delta_y;
 	int8 delta_z;
 	byte size_x;
@@ -33,9 +34,10 @@ struct DrawTileSeqStruct {
 	PalSpriteID image;
 };
 
+/** Ground palette sprite of a tile, together with its child sprites */
 struct DrawTileSprites {
-	PalSpriteID ground;
-	const DrawTileSeqStruct *seq;
+	PalSpriteID ground;           ///< Palette and sprite for the ground
+	const DrawTileSeqStruct *seq; ///< Array of child sprites. Terminated with a terminator entry
 };
 
 /**
diff --git a/src/table/station_land.h b/src/table/station_land.h
index 249b6f482..0cad540d9 100644
--- a/src/table/station_land.h
+++ b/src/table/station_land.h
@@ -2,8 +2,30 @@
 
 /** @file station_land.h Sprites to use and how to display them for station tiles. */
 
+/**
+ * Constructor macro for an image without a palette in a DrawTileSeqStruct array.
+ * @param dx  Offset in x direction
+ * @param dy  Offset in y direction
+ * @param dz  Offset in z direction
+ * @param sx  Size in x direction
+ * @param sy  Size in y direction
+ * @param sz  Size in z direction
+ * @param img Sprite to draw
+ */
 #define TILE_SEQ_LINE(dx, dy, dz, sx, sy, sz, img) { dx, dy, dz, sx, sy, sz, {img, PAL_NONE} },
+/**
+ * Constructor macro for an image with a palette in a DrawTileSeqStruct array.
+ * @param dx  Offset in x direction
+ * @param dy  Offset in y direction
+ * @param dz  Offset in z direction
+ * @param sx  Size in x direction
+ * @param sy  Size in y direction
+ * @param sz  Size in z direction
+ * @param img Sprite to draw
+ * @param pal Paleltte sprite
+ */
 #define TILE_SEQ_LINE_PAL(dx, dy, dz, sx, sy, sz, img, pal) { dx, dy, dz, sx, sy, sz, {img, pal} },
+/** Constructor macro for a terminating DrawTileSeqStruct entry in an array */
 #define TILE_SEQ_END() { (byte)0x80, 0, 0, 0, 0, 0, {0, 0} }
 
 static const DrawTileSeqStruct _station_display_nothing[] = {
@@ -995,6 +1017,11 @@ static const DrawTileSeqStruct _station_display_datas_0171[] = {
 #undef TILE_SEQ_LINE
 #undef TILE_SEQ_LINE_PAL
 
+/**
+ * Constructor macro of a DrawTileSprites structure
+ * @param img   Ground sprite without palette of the tile
+ * @param dtss  Sequence child sprites of the tile
+ */
 #define TILE_SPRITE_LINE(img, dtss) { {img, PAL_NONE}, dtss },
 
 static const DrawTileSprites _station_display_datas_rail[] = {
diff --git a/src/tile_cmd.h b/src/tile_cmd.h
index fc6f56846..d106d5d79 100644
--- a/src/tile_cmd.h
+++ b/src/tile_cmd.h
@@ -102,6 +102,9 @@ typedef Foundation GetFoundationProc(TileIndex tile, Slope tileh);
  */
 typedef CommandCost TerraformTileProc(TileIndex tile, uint32 flags, uint z_new, Slope tileh_new);
 
+/**
+ * Set of callback functions for performing tile operations of a given tile type.
+ * @see TileType */
 struct TileTypeProcs {
 	DrawTileProc *draw_tile_proc;
 	GetSlopeZProc *get_slope_z_proc;
diff --git a/src/tile_type.h b/src/tile_type.h
index 2d46a74d5..229dcee15 100644
--- a/src/tile_type.h
+++ b/src/tile_type.h
@@ -18,7 +18,7 @@ enum {
 
 
 /**
- * The different type of a tile.
+ * The different types of tiles.
  *
  * Each tile belongs to one type, according whatever is build on it.
  *
diff --git a/src/viewport.cpp b/src/viewport.cpp
index c1e9e4d7b..48045542c 100644
--- a/src/viewport.cpp
+++ b/src/viewport.cpp
@@ -83,6 +83,7 @@ struct ChildScreenSpriteToDraw {
 	int next;                       ///< next child to draw (-1 at the end)
 };
 
+/** Parent sprite that should be drawn */
 struct ParentSpriteToDraw {
 	SpriteID image;                 ///< sprite to draw
 	SpriteID pal;                   ///< palette to use
@@ -105,7 +106,7 @@ struct ParentSpriteToDraw {
 	bool comparison_done;           ///< Used during sprite sorting: true if sprite has been compared with all other sprites
 };
 
-/* Enumeration of multi-part foundations */
+/** Enumeration of multi-part foundations */
 enum FoundationPart {
 	FOUNDATION_PART_NONE     = 0xFF,  ///< Neither foundation nor groundsprite drawn yet.
 	FOUNDATION_PART_NORMAL   = 0,     ///< First part (normal foundation or no foundation)
@@ -119,13 +120,14 @@ typedef SmallVector<ParentSpriteToDraw, 64> ParentSpriteToDrawVector;
 typedef SmallVector<ParentSpriteToDraw*, 64> ParentSpriteToSortVector;
 typedef SmallVector<ChildScreenSpriteToDraw, 16> ChildScreenSpriteToDrawVector;
 
+/** Data structure storing rendering information */
 struct ViewportDrawer {
 	DrawPixelInfo dpi;
 
 	StringSpriteToDrawVector string_sprites_to_draw;
 	TileSpriteToDrawVector tile_sprites_to_draw;
 	ParentSpriteToDrawVector parent_sprites_to_draw;
-	ParentSpriteToSortVector parent_sprites_to_sort;
+	ParentSpriteToSortVector parent_sprites_to_sort; ///< Parent sprite pointer array used for sorting
 	ChildScreenSpriteToDrawVector child_screen_sprites_to_draw;
 
 	int *last_child;
@@ -356,6 +358,12 @@ ViewPort *IsPtInWindowViewport(const Window *w, int x, int y)
 	return NULL;
 }
 
+/**
+ * Translate screen coordinate in a viewport to a tile coordinate
+ * @param vp  Viewport that contains the (\a x, \a y) screen coordinate
+ * @param x   Screen x coordinate
+ * @param y   Screen y coordinate
+ * @return Tile coordinate */
 static Point TranslateXYToTileCoord(const ViewPort *vp, int x, int y)
 {
 	Point pt;
@@ -1286,6 +1294,7 @@ static void ViewportDrawTileSprites(const TileSpriteToDrawVector *tstdv)
 	}
 }
 
+/** Sort parent sprites pointer array */
 static void ViewportSortParentSprites(ParentSpriteToSortVector *psdv)
 {
 	ParentSpriteToDraw **psdvend = psdv->End();