(svn r9729) -Documentation: add some documentation in various places

src/map.cpp

@@ -16,24 +16,29 @@
 extern "C" _CRTIMP void __cdecl _assert(void *, void *, unsigned);
 #endif
 
-uint _map_log_x;
-uint _map_size_x;
-uint _map_size_y;
-uint _map_tile_mask;
-uint _map_size;
+uint _map_log_x;     ///< 2^_map_log_x == _map_size_x
+uint _map_size_x;    ///< Size of the map along the X
+uint _map_size_y;    ///< Size of the map along the Y
+uint _map_size;      ///< The number of tiles on the map
+uint _map_tile_mask; ///< _map_size - 1 (to mask the mapsize)
 
-Tile *_m = NULL;
-TileExtended *_me = NULL;
+Tile *_m = NULL;          ///< Tiles of the map
+TileExtended *_me = NULL; ///< Extended Tiles of the map
 
 
+/**
+ * (Re)allocates a map with the given dimension
+ * @param size_x the width of the map along the NE/SW edge
+ * @param size_y the 'height' of the map along the SE/NW edge
+ */
 void AllocateMap(uint size_x, uint size_y)
 {
 	/* Make sure that the map size is within the limits and that
 	 * the x axis size is a power of 2. */
 	if (size_x < 64 || size_x > 2048 ||
 			size_y < 64 || size_y > 2048 ||
-			(size_x&(size_x-1)) != 0 ||
-			(size_y&(size_y-1)) != 0)
+			(size_x & (size_x - 1)) != 0 ||
+			(size_y & (size_y - 1)) != 0)
 		error("Invalid map size");
 
 	DEBUG(map, 1, "Allocating map of size %dx%d", size_x, size_y);
@@ -92,7 +97,12 @@ TileIndex TileAdd(TileIndex tile, TileIndexDiff add,
 }
 #endif
 
-
+/**
+ * Scales the given value by the map size, where the given value is
+ * for a 256 by 256 map
+ * @param n the value to scale
+ * @return the scaled size
+ */
 uint ScaleByMapSize(uint n)
 {
 	/* First shift by 12 to prevent integer overflow for large values of n.
@@ -102,7 +112,12 @@ uint ScaleByMapSize(uint n)
 }
 
 
-/* Scale relative to the circumference of the map */
+/**
+ * Scales the given value by the maps circumference, where the given
+ * value is for a 256 by 256 map
+ * @param n the value to scale
+ * @return the scaled size
+ */
 uint ScaleByMapSize1D(uint n)
 {
 	/* Normal circumference for the X+Y is 256+256 = 1<<9
@@ -113,12 +128,18 @@ uint ScaleByMapSize1D(uint n)
 }
 
 
-/* This function checks if we add addx/addy to tile, if we
+/**
+ * This function checks if we add addx/addy to tile, if we
  *  do wrap around the edges. For example, tile = (10,2) and
  *  addx = +3 and addy = -4. This function will now return
  *  INVALID_TILE, because the y is wrapped. This is needed in
  *  for example, farmland. When the tile is not wrapped,
- *  the result will be tile + TileDiffXY(addx, addy) */
+ *  the result will be tile + TileDiffXY(addx, addy)
+ * @param tile the 'starting' point of the adding
+ * @param addx the amount of tiles in the X direction to add
+ * @param addy the amount of tiles in the Y direction to add
+ * @return translated tile, or INVALID_TILE when it would've wrapped.
+ */
 uint TileAddWrap(TileIndex tile, int addx, int addy)
 {
 	uint x = TileX(tile) + addx;
@@ -131,6 +152,7 @@ uint TileAddWrap(TileIndex tile, int addx, int addy)
 	return INVALID_TILE;
 }
 
+/** 'Lookup table' for tile offsets given a DiagDirection */
 extern const TileIndexDiffC _tileoffs_by_diagdir[] = {
 	{-1,  0}, ///< DIAGDIR_NE
 	{ 0,  1}, ///< DIAGDIR_SE
@@ -138,6 +160,7 @@ extern const TileIndexDiffC _tileoffs_by_diagdir[] = {
 	{ 0, -1}  ///< DIAGDIR_NW
 };
 
+/** 'Lookup table' for tile offsets given a Direction */
 extern const TileIndexDiffC _tileoffs_by_dir[] = {
 	{-1, -1}, ///< DIR_N
 	{-1,  0}, ///< DIR_NE
@@ -149,6 +172,15 @@ extern const TileIndexDiffC _tileoffs_by_dir[] = {
 	{ 0, -1}  ///< DIR_NW
 };
 
+/**
+ * Gets the Manhattan distance between the two given tiles.
+ * The Manhattan distance is the sum of the delta of both the
+ * X and Y component.
+ * Also known as L1-Norm
+ * @param t0 the start tile
+ * @param t1 the end tile
+ * @return the distance
+ */
 uint DistanceManhattan(TileIndex t0, TileIndex t1)
 {
 	const uint dx = delta(TileX(t0), TileX(t1));
@@ -157,6 +189,15 @@ uint DistanceManhattan(TileIndex t0, TileIndex t1)
 }
 
 
+/**
+ * Gets the 'Square' distance between the two given tiles.
+ * The 'Square' distance is the square of the shortest (straight line)
+ * distance between the two tiles.
+ * Also known as euclidian- or L2-Norm squared.
+ * @param t0 the start tile
+ * @param t1 the end tile
+ * @return the distance
+ */
 uint DistanceSquare(TileIndex t0, TileIndex t1)
 {
 	const int dx = TileX(t0) - TileX(t1);
@@ -165,6 +206,13 @@ uint DistanceSquare(TileIndex t0, TileIndex t1)
 }
 
 
+/**
+ * Gets the biggest distance component (x or y) between the two given tiles.
+ * Also known as L-Infinity-Norm.
+ * @param t0 the start tile
+ * @param t1 the end tile
+ * @return the distance
+ */
 uint DistanceMax(TileIndex t0, TileIndex t1)
 {
 	const uint dx = delta(TileX(t0), TileX(t1));
@@ -173,6 +221,14 @@ uint DistanceMax(TileIndex t0, TileIndex t1)
 }
 
 
+/**
+ * Gets the biggest distance component (x or y) between the two given tiles
+ * plus the Manhattan distance, i.e. two times the biggest distance component
+ * and once the smallest component.
+ * @param t0 the start tile
+ * @param t1 the end tile
+ * @return the distance
+ */
 uint DistanceMaxPlusManhattan(TileIndex t0, TileIndex t1)
 {
 	const uint dx = delta(TileX(t0), TileX(t1));
@@ -180,6 +236,11 @@ uint DistanceMaxPlusManhattan(TileIndex t0, TileIndex t1)
 	return dx > dy ? 2 * dx + dy : 2 * dy + dx;
 }
 
+/**
+ * Param the minimum distance to an edge
+ * @param tile the tile to get the distance from
+ * @return the distance from the edge in tiles
+ */
 uint DistanceFromEdge(TileIndex tile)
 {
 	const uint xl = TileX(tile);