(svn r11066) -Documentation [FS#1091]: of map.*. Patch by Progman.

1 files changed, 149 insertions, 13 deletions

diff --git a/src/map.h b/src/map.h
index 811a12bca..9e28b0732 100644
--- a/src/map.h
+++ b/src/map.h
@@ -45,9 +45,25 @@ struct TileExtended {
 	byte m7; ///< Primarily used for newgrf support
 };
 
+/**
+ * Pointer to the tile-array.
+ *
+ * This variable points to the tile-array which contains the tiles of
+ * the map.
+ */
 extern Tile *_m;
+
+/**
+ * Pointer to the extended tile-array.
+ *
+ * This variable points to the extended tile-array which contains the tiles
+ * of the map.
+ */
 extern TileExtended *_me;
 
+/**
+ * Allocate a new map with the given size.
+ */
 void AllocateMap(uint size_x, uint size_y);
 
 /**
@@ -109,18 +125,56 @@ static inline uint MapMaxY()
 	return MapSizeY() - 1;
 }
 
-/* Scale a number relative to the map size */
-uint ScaleByMapSize(uint); // Scale relative to the number of tiles
-uint ScaleByMapSize1D(uint); // Scale relative to the circumference of the map
+/**
+ * Scales relative to the number of tiles.
+ */
+uint ScaleByMapSize(uint);
+
+/**
+ * Scale relative to the circumference of the map.
+ */
+uint ScaleByMapSize1D(uint);
 
+/**
+ * The index/ID of a Tile.
+ */
 typedef uint32 TileIndex;
+
+/**
+ * An offset value between to tiles.
+ *
+ * This value is used fro the difference between
+ * to tiles. It can be added to a tileindex to get
+ * the resulting tileindex of the start tile applied
+ * with this saved difference.
+ *
+ * @see TileDiffXY(int, int)
+ */
 typedef int32 TileIndexDiff;
 
+/**
+ * Returns the TileIndex of a coordinate.
+ *
+ * @param x The x coordinate of the tile
+ * @param y The y coordinate of the tile
+ * @return The TileIndex calculated by the coordinate
+ */
 static inline TileIndex TileXY(uint x, uint y)
 {
 	return (y * MapSizeX()) + x;
 }
 
+/**
+ * Calculates an offset for the given coordinate(-offset).
+ *
+ * This function calculate an offset value which can be added to an
+ * #TileIndex. The coordinates can be negative.
+ *
+ * @param x The offset in x direction
+ * @param y The offset in y direction
+ * @return The resulting offset value of the given coordinate
+ * @see ToTileIndexDiff(TileIndexDiffC)
+ */
 static inline TileIndexDiff TileDiffXY(int x, int y)
 {
 	/* Multiplication gives much better optimization on MSVC than shifting.
@@ -167,12 +221,27 @@ static inline uint TileY(TileIndex tile)
 	return tile >> MapLogX();
 }
 
-
+/**
+ * A pair-construct of a TileIndexDiff.
+ *
+ * This can be used to save the difference between to
+ * tiles as a pair of x and y value.
+ */
 struct TileIndexDiffC {
-	int16 x;
-	int16 y;
+	int16 x;        ///< The x value of the coordinate
+	int16 y;        ///< The y value of the coordinate
 };
 
+/**
+ * Return the offset between to tiles from a TileIndexDiffC struct.
+ *
+ * This function works like #TileDiffXY(int, int) and returns the
+ * difference between two tiles.
+ *
+ * @param tidc The coordinate of the offset as TileIndexDiffC
+ * @return The difference between two tiles.
+ * @see TileDiffXY(int, int)
+ */
 static inline TileIndexDiff ToTileIndexDiff(TileIndexDiffC tidc)
 {
 	return (tidc.y << MapLogX()) + tidc.x;
@@ -180,6 +249,13 @@ static inline TileIndexDiff ToTileIndexDiff(TileIndexDiffC tidc)
 
 
 #ifndef _DEBUG
+        /**
+         * Adds to tiles together.
+         *
+         * @param x One tile
+         * @param y An other tile to add
+         * @return The resulting tile(index)
+         */
 	#define TILE_ADD(x,y) ((x) + (y))
 #else
 	extern TileIndex TileAdd(TileIndex tile, TileIndexDiff add,
@@ -187,10 +263,26 @@ static inline TileIndexDiff ToTileIndexDiff(TileIndexDiffC tidc)
 	#define TILE_ADD(x, y) (TileAdd((x), (y), #x " + " #y, __FILE__, __LINE__))
 #endif
 
+/**
+ * Adds a given offset to a tile.
+ *
+ * @param tile The tile to add an offset on it
+ * @param x The x offset to add to the tile
+ * @param y The y offset to add to the tile
+ */
 #define TILE_ADDXY(tile, x, y) TILE_ADD(tile, TileDiffXY(x, y))
 
+/**
+ * Adds an offset to a tile and check if we are still on the map.
+ */
 uint TileAddWrap(TileIndex tile, int addx, int addy);
 
+/**
+ * Returns the TileIndexDiffC offset from a DiagDirection.
+ *
+ * @param dir The given direction
+ * @return The offset as TileIndexDiffC value
+ */
 static inline TileIndexDiffC TileIndexDiffCByDiagDir(DiagDirection dir)
 {
 	extern const TileIndexDiffC _tileoffs_by_diagdir[DIAGDIR_END];
@@ -198,9 +290,15 @@ static inline TileIndexDiffC TileIndexDiffCByDiagDir(DiagDirection dir)
 	assert(IsValidDiagDirection(dir));
 	return _tileoffs_by_diagdir[dir];
 }
-
-/* Returns tile + the diff given in diff. If the result tile would end up
+/**
+ * Add a TileIndexDiffC to a TileIndex and returns the new one.
+ *
+ * Returns tile + the diff given in diff. If the result tile would end up
  * outside of the map, INVALID_TILE is returned instead.
+ *
+ * @param tile The base tile to add the offset on
+ * @param diff The offset to add on the tile
+ * @return The resulting TileIndex
  */
 static inline TileIndex AddTileIndexDiffCWrap(TileIndex tile, TileIndexDiffC diff)
 {
@@ -236,7 +334,16 @@ uint DistanceMax(TileIndex, TileIndex); ///< also known as L-Infinity-Norm
 uint DistanceMaxPlusManhattan(TileIndex, TileIndex); ///< Max + Manhattan
 uint DistanceFromEdge(TileIndex); ///< shortest distance from any edge of the map
 
-
+/**
+ * Starts a loop which iterates to a square of tiles
+ *
+ * This macro starts 2 nested loops which iterates over a square of tiles.
+ *
+ * @param var The name of the variable which contains the current tile
+ * @param w The width (x-width) of the square
+ * @param h The heigth (y-width) of the square
+ * @param tile The start tile of the square
+ */
 #define BEGIN_TILE_LOOP(var, w, h, tile)                      \
 	{                                                        \
 		int h_cur = h;                                         \
@@ -244,12 +351,22 @@ uint DistanceFromEdge(TileIndex); ///< shortest distance from any edge of the ma
 		do {                                                   \
 			int w_cur = w;                                       \
 			do {
-
+/**
+ * Ends the square-loop used before
+ *
+ * @see BEGIN_TILE_LOOP
+ */
 #define END_TILE_LOOP(var, w, h, tile)                        \
 			} while (++var, --w_cur != 0);                       \
 		} while (var += TileDiffXY(0, 1) - (w), --h_cur != 0); \
 	}
-
+/**
+ * Convert a DiagDirection to a TileIndexDiff
+ *
+ * @param dir The DiagDirection
+ * @return The resulting TileIndexDiff
+ * @see TileIndexDiffCByDiagDir
+ */
 static inline TileIndexDiff TileOffsByDiagDir(DiagDirection dir)
 {
 	extern const TileIndexDiffC _tileoffs_by_diagdir[DIAGDIR_END];
@@ -258,6 +375,12 @@ static inline TileIndexDiff TileOffsByDiagDir(DiagDirection dir)
 	return ToTileIndexDiff(_tileoffs_by_diagdir[dir]);
 }
 
+/**
+ * Convert a Direction to a TileIndexDiff.
+ *
+ * @param dir The direction to convert from
+ * @return The resulting TileIndexDiff
+ */
 static inline TileIndexDiff TileOffsByDir(Direction dir)
 {
 	extern const TileIndexDiffC _tileoffs_by_dir[DIR_END];
@@ -266,11 +389,24 @@ static inline TileIndexDiff TileOffsByDir(Direction dir)
 	return ToTileIndexDiff(_tileoffs_by_dir[dir]);
 }
 
+/**
+ * A callback function type for searching tiles.
+ *
+ * @param tile The tile to test
+ * @param data additional data for the callback function to use
+ * @return A boolean value, depend on the definition of the function.
+ */
 typedef bool TestTileOnSearchProc(TileIndex tile, uint32 data);
+
+/**
+ * Searches for some cirumstances of a tile around a given tile with a helper function.
+ */
 bool CircularTileSearch(TileIndex tile, uint size, TestTileOnSearchProc proc, uint32 data);
 
-/* Approximation of the length of a straight track, relative to a diagonal
- * track (ie the size of a tile side). #defined instead of const so it can
+/** Approximation of the length of a straight track, relative to a diagonal
+ * track (ie the size of a tile side).
+ *
+ * #defined instead of const so it can
  * stay integer. (no runtime float operations) Is this needed?
  * Watch out! There are _no_ brackets around here, to prevent intermediate
  * rounding! Be careful when using this!