(svn r21845) -Codechange: move documentation towards the code to make it more likely to be updates [d-m].

22 files changed, 144 insertions, 185 deletions

diff --git a/src/company_cmd.cpp b/src/company_cmd.cpp
index 7246a0172..9ae1b1dbb 100644
--- a/src/company_cmd.cpp
+++ b/src/company_cmd.cpp
@@ -501,6 +501,11 @@ restart:;
 	}
 }
 
+/**
+ * Reset the livery schemes to the company's primary colour.
+ * This is used on loading games without livery information and on new company start up.
+ * @param c Company to reset.
+ */
 void ResetCompanyLivery(Company *c)
 {
 	for (LiveryScheme scheme = LS_BEGIN; scheme < LS_END; scheme++) {
diff --git a/src/elrail.cpp b/src/elrail.cpp
index 7bc8f98b0..701d17a26 100644
--- a/src/elrail.cpp
+++ b/src/elrail.cpp
@@ -473,6 +473,13 @@ static void DrawCatenaryRailway(const TileInfo *ti)
 	}
 }
 
+/**
+ * Draws wires on a tunnel tile
+ *
+ * DrawTile_TunnelBridge() calls this function to draw the wires on the bridge.
+ *
+ * @param ti The Tileinfo to draw the tile for
+ */
 void DrawCatenaryOnBridge(const TileInfo *ti)
 {
 	TileIndex end = GetSouthernBridgeEnd(ti->tile);
@@ -530,6 +537,11 @@ void DrawCatenaryOnBridge(const TileInfo *ti)
 	}
 }
 
+/**
+ * Draws overhead wires and pylons for electric railways.
+ * @param ti The TileInfo struct of the tile being drawn
+ * @see DrawCatenaryRailway
+ */
 void DrawCatenary(const TileInfo *ti)
 {
 	switch (GetTileType(ti->tile)) {
diff --git a/src/elrail_func.h b/src/elrail_func.h
index e72f78425..60cb782bb 100644
--- a/src/elrail_func.h
+++ b/src/elrail_func.h
@@ -34,11 +34,6 @@ static inline bool HasCatenaryDrawn(RailType rt)
 	return HasCatenary(rt) && !IsInvisibilitySet(TO_CATENARY) && !_settings_game.vehicle.disable_elrails;
 }
 
-/**
- * Draws overhead wires and pylons for electric railways.
- * @param ti The TileInfo struct of the tile being drawn
- * @see DrawCatenaryRailway
- */
 void DrawCatenary(const TileInfo *ti);
 void DrawCatenaryOnTunnel(const TileInfo *ti);
 void DrawCatenaryOnBridge(const TileInfo *ti);
diff --git a/src/functions.h b/src/functions.h
index 882a23f12..b8cbdd137 100644
--- a/src/functions.h
+++ b/src/functions.h
@@ -28,11 +28,6 @@ CommandCost CheckOwnership(Owner owner, TileIndex tile = 0);
 CommandCost CheckTileOwnership(TileIndex tile);
 
 /* misc functions */
-/**
- * Mark a tile given by its index dirty for repaint.
- *
- * @ingroup dirty
- */
 void MarkTileDirtyByTile(TileIndex tile);
 
 void ShowCostOrIncomeAnimation(int x, int y, int z, Money cost);
diff --git a/src/gfx.cpp b/src/gfx.cpp
index 410ea6686..7fad4f15b 100644
--- a/src/gfx.cpp
+++ b/src/gfx.cpp
@@ -1559,7 +1559,7 @@ void RedrawScreenRect(int left, int top, int right, int bottom)
 	_video_driver->MakeDirty(left, top, right - left, bottom - top);
 }
 
-/*!
+/**
  * Repaints the rectangle blocks which are marked as 'dirty'.
  *
  * @see SetDirtyBlocks
@@ -1653,7 +1653,7 @@ void DrawDirtyBlocks()
 	_invalid_rect.bottom = 0;
 }
 
-/*!
+/**
  * This function extends the internal _invalid_rect rectangle as it
  * now contains the rectangle defined by the given parameters. Note
  * the point (0,0) is top left.
@@ -1705,10 +1705,11 @@ void SetDirtyBlocks(int left, int top, int right, int bottom)
 	} while (--height != 0);
 }
 
-/*!
+/**
  * This function mark the whole screen as dirty. This results in repainting
  * the whole screen. Use this with care as this function will break the
  * idea about marking only parts of the screen as 'dirty'.
+ * @ingroup dirty
  */
 void MarkWholeScreenDirty()
 {
diff --git a/src/gfx_func.h b/src/gfx_func.h
index 41d623f94..9a0c3e63f 100644
--- a/src/gfx_func.h
+++ b/src/gfx_func.h
@@ -128,25 +128,8 @@ int GetStringHeight(StringID str, int maxw);
 Dimension GetStringMultiLineBoundingBox(StringID str, const Dimension &suggestion);
 void LoadStringWidthTable();
 
-/**
- * Let the dirty blocks repainting by the video driver.
- *
- * @ingroup dirty
- */
 void DrawDirtyBlocks();
-
-/**
- * Set a new dirty block.
- *
- * @ingroup dirty
- */
 void SetDirtyBlocks(int left, int top, int right, int bottom);
-
-/**
- * Marks the whole screen as dirty.
- *
- * @ingroup dirty
- */
 void MarkWholeScreenDirty();
 
 void GfxInitPalettes();
diff --git a/src/group.h b/src/group.h
index 1061b0e8e..46a12d9e2 100644
--- a/src/group.h
+++ b/src/group.h
@@ -67,14 +67,6 @@ static inline uint GetGroupArraySize()
 	return num;
 }
 
-/**
- * Get the number of engines with EngineID id_e in the group with GroupID
- * id_g
- * @param company The company the group belongs to
- * @param id_g The GroupID of the group used
- * @param id_e The EngineID of the engine to count
- * @return The number of engines with EngineID id_e in the group
- */
 uint GetGroupNumEngines(CompanyID company, GroupID id_g, EngineID id_e);
 
 static inline void IncreaseGroupNumVehicle(GroupID id_g)
diff --git a/src/group_cmd.cpp b/src/group_cmd.cpp
index ba68515fd..cfa6a3fb5 100644
--- a/src/group_cmd.cpp
+++ b/src/group_cmd.cpp
@@ -409,6 +409,14 @@ void UpdateTrainGroupID(Train *v)
 	SetWindowDirty(WC_REPLACE_VEHICLE, VEH_TRAIN);
 }
 
+/**
+ * Get the number of engines with EngineID id_e in the group with GroupID
+ * id_g
+ * @param company The company the group belongs to
+ * @param id_g The GroupID of the group used
+ * @param id_e The EngineID of the engine to count
+ * @return The number of engines with EngineID id_e in the group
+ */
 uint GetGroupNumEngines(CompanyID company, GroupID id_g, EngineID id_e)
 {
 	if (Group::IsValidID(id_g)) return Group::Get(id_g)->num_engines[id_e];
diff --git a/src/heightmap.cpp b/src/heightmap.cpp
index 9b72a873f..8790da59e 100644
--- a/src/heightmap.cpp
+++ b/src/heightmap.cpp
@@ -430,11 +430,24 @@ static bool ReadHeightMap(char *filename, uint *x, uint *y, byte **map)
 	}
 }
 
+/**
+ * Get the dimensions of a heightmap.
+ * @param filename to query
+ * @param x dimension x
+ * @param y dimension y
+ * @return Returns false if loading of the image failed.
+ */
 bool GetHeightmapDimensions(char *filename, uint *x, uint *y)
 {
 	return ReadHeightMap(filename, x, y, NULL);
 }
 
+/**
+ * Load a heightmap from file and change the map in his current dimensions
+ *  to a landscape representing the heightmap.
+ * It converts pixels to height. The brighter, the higher.
+ * @param filename of the heighmap file to be imported
+ */
 void LoadHeightmap(char *filename)
 {
 	uint x, y;
@@ -452,6 +465,10 @@ void LoadHeightmap(char *filename)
 	MarkWholeScreenDirty();
 }
 
+/**
+ * Make an empty world where all tiles are of height 'tile_height'.
+ * @param tile_height of the desired new empty world
+ */
 void FlatEmptyWorld(byte tile_height)
 {
 	int edge_distance = _settings_game.construction.freeform_edges ? 0 : 2;
diff --git a/src/heightmap.h b/src/heightmap.h
index 16ef279c7..08ae200ec 100644
--- a/src/heightmap.h
+++ b/src/heightmap.h
@@ -12,7 +12,7 @@
 #ifndef HEIGHTMAP_H
 #define HEIGHTMAP_H
 
-/*
+/**
  * Order of these enums has to be the same as in lang/english.txt
  * Otherwise you will get inconsistent behaviour.
  */
@@ -21,33 +21,9 @@ enum HeightmapRotation {
 	HM_CLOCKWISE,         ///< Rotate the map clockwise 45 degrees
 };
 
-/**
- * Get the dimensions of a heightmap.
- * @param filename to query
- * @param x dimension x
- * @param y dimension y
- * @return Returns false if loading of the image failed.
- */
 bool GetHeightmapDimensions(char *filename, uint *x, uint *y);
-
-/**
- * Load a heightmap from file and change the map in his current dimensions
- *  to a landscape representing the heightmap.
- * It converts pixels to height. The brighter, the higher.
- * @param filename of the heighmap file to be imported
- */
 void LoadHeightmap(char *filename);
-
-/**
- * Make an empty world where all tiles are of height 'tile_height'.
- * @param tile_height of the desired new empty world
- */
 void FlatEmptyWorld(byte tile_height);
-
-/**
- * This function takes care of the fact that land in OpenTTD can never differ
- * more than 1 in height
- */
 void FixSlopes();
 
 #endif /* HEIGHTMAP_H */
diff --git a/src/house.h b/src/house.h
index e1ecce25b..e738b6873 100644
--- a/src/house.h
+++ b/src/house.h
@@ -121,10 +121,6 @@ struct HouseSpec {
 	byte processing_time;              ///< Periodic refresh multiplier
 	byte minimum_life;                 ///< The minimum number of years this house will survive before the town rebuilds it
 
-	/**
-	 * Get the cost for removing this house
-	 * @return the cost (inflation corrected etc)
-	 */
 	Money GetRemovalCost() const;
 
 	static FORCEINLINE HouseSpec *Get(size_t house_id)
diff --git a/src/industry_cmd.cpp b/src/industry_cmd.cpp
index 398b3f1c3..782e93e73 100644
--- a/src/industry_cmd.cpp
+++ b/src/industry_cmd.cpp
@@ -2644,6 +2644,10 @@ void InitializeIndustries()
 	_industry_builder.Reset();
 }
 
+/**
+ * Is an industry with the spec a raw industry?
+ * @return true if it should be handled as a raw industry
+ */
 bool IndustrySpec::IsRawIndustry() const
 {
 	/* Lumber mills are extractive/organic, but can always be built like a non-raw industry */
@@ -2651,6 +2655,10 @@ bool IndustrySpec::IsRawIndustry() const
 			(this->behaviour & INDUSTRYBEH_CUT_TREES) == 0;
 }
 
+/**
+ * Get the cost for constructing this industry
+ * @return the cost (inflation corrected etc)
+ */
 Money IndustrySpec::GetConstructionCost() const
 {
 	/* Building raw industries like secondary uses different price base */
@@ -2658,11 +2666,21 @@ Money IndustrySpec::GetConstructionCost() const
 			PR_BUILD_INDUSTRY_RAW : PR_BUILD_INDUSTRY] * this->cost_multiplier) >> 8;
 }
 
+/**
+ * Get the cost for removing this industry
+ * Take note that the cost will always be zero for non-grf industries.
+ * Only if the grf author did specified a cost will it be applicable.
+ * @return the cost (inflation corrected etc)
+ */
 Money IndustrySpec::GetRemovalCost() const
 {
 	return (_price[PR_CLEAR_INDUSTRY] * this->removal_cost_multiplier) >> 8;
 }
 
+/**
+ * Determines whether this industrytype uses smooth economy or whether it uses standard/newgrf production changes.
+ * @return true if smooth economy is used.
+ */
 bool IndustrySpec::UsesSmoothEconomy() const
 {
 	return _settings_game.economy.smooth_economy &&
diff --git a/src/industrytype.h b/src/industrytype.h
index 32f3c2b51..b7b794a43 100644
--- a/src/industrytype.h
+++ b/src/industrytype.h
@@ -134,30 +134,9 @@ struct IndustrySpec {
 	bool enabled;                         ///< entity still available (by default true).newgrf can disable it, though
 	GRFFileProps grf_prop;                ///< properties related to the grf file
 
-	/**
-	 * Is an industry with the spec a raw industry?
-	 * @return true if it should be handled as a raw industry
-	 */
 	bool IsRawIndustry() const;
-
-	/**
-	 * Get the cost for constructing this industry
-	 * @return the cost (inflation corrected etc)
-	 */
 	Money GetConstructionCost() const;
-
-	/**
-	 * Get the cost for removing this industry
-	 * Take note that the cost will always be zero for non-grf industries.
-	 * Only if the grf author did specified a cost will it be applicable.
-	 * @return the cost (inflation corrected etc)
-	 */
 	Money GetRemovalCost() const;
-
-	/**
-	 * Determines whether this industrytype uses smooth economy or whether it uses standard/newgrf production changes.
-	 * @return true if smooth economy is used.
-	 */
 	bool UsesSmoothEconomy() const;
 };
 
diff --git a/src/ini.cpp b/src/ini.cpp
index d79189bd2..dc658296e 100644
--- a/src/ini.cpp
+++ b/src/ini.cpp
@@ -26,6 +26,12 @@
 # include <shellapi.h>
 #endif
 
+/**
+ * Construct a new in-memory item of an Ini file.
+ * @param parent the group we belong to
+ * @param name   the name of the item
+ * @param len    the length of the name of the item
+ */
 IniItem::IniItem(IniGroup *parent, const char *name, size_t len) : next(NULL), value(NULL), comment(NULL)
 {
 	if (len == 0) len = strlen(name);
@@ -35,6 +41,7 @@ IniItem::IniItem(IniGroup *parent, const char *name, size_t len) : next(NULL), v
 	parent->last_item = &this->next;
 }
 
+/** Free everything we loaded. */
 IniItem::~IniItem()
 {
 	free(this->name);
@@ -44,12 +51,22 @@ IniItem::~IniItem()
 	delete this->next;
 }
 
+/**
+ * Replace the current value with another value.
+ * @param value the value to replace with.
+ */
 void IniItem::SetValue(const char *value)
 {
 	free(this->value);
 	this->value = strdup(value);
 }
 
+/**
+ * Construct a new in-memory group of an Ini file.
+ * @param parent the file we belong to
+ * @param name   the name of the group
+ * @param len    the length of the name of the group
+ */
 IniGroup::IniGroup(IniFile *parent, const char *name, size_t len) : next(NULL), type(IGT_VARIABLES), item(NULL), comment(NULL)
 {
 	if (len == 0) len = strlen(name);
@@ -69,6 +86,7 @@ IniGroup::IniGroup(IniFile *parent, const char *name, size_t len) : next(NULL),
 	}
 }
 
+/** Free everything we loaded. */
 IniGroup::~IniGroup()
 {
 	free(this->name);
@@ -78,6 +96,13 @@ IniGroup::~IniGroup()
 	delete this->next;
 }
 
+/**
+ * Get the item with the given name, and if it doesn't exist
+ * and create is true it creates a new item.
+ * @param name   name of the item to find.
+ * @param create whether to create an item when not found or not.
+ * @return the requested item or NULL if not found.
+ */
 IniItem *IniGroup::GetItem(const char *name, bool create)
 {
 	for (IniItem *item = this->item; item != NULL; item = item->next) {
@@ -90,6 +115,9 @@ IniItem *IniGroup::GetItem(const char *name, bool create)
 	return new IniItem(this, name, strlen(name));
 }
 
+/**
+ * Clear all items in the group
+ */
 void IniGroup::Clear()
 {
 	delete this->item;
@@ -97,17 +125,30 @@ void IniGroup::Clear()
 	this->last_item = &this->item;
 }
 
+/**
+ * Construct a new in-memory Ini file representation.
+ * @param list_group_names A NULL terminated list with groups that should be
+ *                         loaded as lists instead of variables.
+ */
 IniFile::IniFile(const char * const *list_group_names) : group(NULL), comment(NULL), list_group_names(list_group_names)
 {
 	this->last_group = &this->group;
 }
 
+/** Free everything we loaded. */
 IniFile::~IniFile()
 {
 	free(this->comment);
 	delete this->group;
 }
 
+/**
+ * Get the group with the given name, and if it doesn't exist
+ * create a new group.
+ * @param name name of the group to find.
+ * @param len  the maximum length of said name.
+ * @return the requested group.
+ */
 IniGroup *IniFile::GetGroup(const char *name, size_t len)
 {
 	if (len == 0) len = strlen(name);
@@ -125,6 +166,10 @@ IniGroup *IniFile::GetGroup(const char *name, size_t len)
 	return group;
 }
 
+/**
+ * Remove the group with the given name.
+ * @param name name of the group to remove.
+ */
 void IniFile::RemoveGroup(const char *name)
 {
 	size_t len = strlen(name);
@@ -152,6 +197,11 @@ void IniFile::RemoveGroup(const char *name)
 	delete group;
 }
 
+/**
+ * Load the Ini file's data from the disk.
+ * @param filename the file to load.
+ * @pre nothing has been loaded yet.
+ */
 void IniFile::LoadFromDisk(const char *filename)
 {
 	assert(this->last_group == &this->group);
@@ -268,6 +318,11 @@ void IniFile::LoadFromDisk(const char *filename)
 	fclose(in);
 }
 
+/**
+ * Save the Ini file's data to the disk.
+ * @param filename the file to save to.
+ * @return true if saving succeeded.
+ */
 bool IniFile::SaveToDisk(const char *filename)
 {
 	/*
diff --git a/src/ini_type.h b/src/ini_type.h
index 45cd75b00..b89a77b56 100644
--- a/src/ini_type.h
+++ b/src/ini_type.h
@@ -25,21 +25,9 @@ struct IniItem {
 	char *value;   ///< The value of this item
 	char *comment; ///< The comment associated with this item
 
-	/**
-	 * Construct a new in-memory item of an Ini file.
-	 * @param parent the group we belong to
-	 * @param name   the name of the item
-	 * @param len    the length of the name of the item
-	 */
 	IniItem(struct IniGroup *parent, const char *name, size_t len = 0);
-
-	/** Free everything we loaded. */
 	~IniItem();
 
-	/**
-	 * Replace the current value with another value.
-	 * @param value the value to replace with.
-	 */
 	void SetValue(const char *value);
 };
 
@@ -52,29 +40,10 @@ struct IniGroup {
 	char *name;          ///< name of group
 	char *comment;       ///< comment for group
 
-	/**
-	 * Construct a new in-memory group of an Ini file.
-	 * @param parent the file we belong to
-	 * @param name   the name of the group
-	 * @param len    the length of the name of the group
-	 */
 	IniGroup(struct IniFile *parent, const char *name, size_t len = 0);
-
-	/** Free everything we loaded. */
 	~IniGroup();
 
-	/**
-	 * Get the item with the given name, and if it doesn't exist
-	 * and create is true it creates a new item.
-	 * @param name   name of the item to find.
-	 * @param create whether to create an item when not found or not.
-	 * @return the requested item or NULL if not found.
-	 */
 	IniItem *GetItem(const char *name, bool create);
-
-	/**
-	 * Clear all items in the group
-	 */
 	void Clear();
 };
 
@@ -85,43 +54,13 @@ struct IniFile {
 	char *comment;                        ///< last comment in file
 	const char * const *list_group_names; ///< NULL terminated list with group names that are lists
 
-	/**
-	 * Construct a new in-memory Ini file representation.
-	 * @param list_group_names A NULL terminated list with groups that should be
-	 *                         loaded as lists instead of variables.
-	 */
 	IniFile(const char * const *list_group_names = NULL);
-
-	/** Free everything we loaded. */
 	~IniFile();
 
-	/**
-	 * Get the group with the given name, and if it doesn't exist
-	 * create a new group.
-	 * @param name name of the group to find.
-	 * @param len  the maximum length of said name.
-	 * @return the requested group.
-	 */
 	IniGroup *GetGroup(const char *name, size_t len = 0);
-
-	/**
-	 * Remove the group with the given name.
-	 * @param name name of the group to remove.
-	 */
 	void RemoveGroup(const char *name);
 
-	/**
-	 * Load the Ini file's data from the disk.
-	 * @param filename the file to load.
-	 * @pre nothing has been loaded yet.
-	 */
 	void LoadFromDisk(const char *filename);
-
-	/**
-	 * Save the Ini file's data to the disk.
-	 * @param filename the file to save to.
-	 * @return true if saving succeeded.
-	 */
 	bool SaveToDisk(const char *filename);
 };
 
diff --git a/src/language.h b/src/language.h
index 1b4fb497a..2f67cd023 100644
--- a/src/language.h
+++ b/src/language.h
@@ -57,10 +57,6 @@ struct LanguagePackHeader {
 	char genders[MAX_NUM_GENDERS][CASE_GENDER_LEN]; ///< the genders used by this translation
 	char cases[MAX_NUM_CASES][CASE_GENDER_LEN];     ///< the cases used by this translation
 
-	/**
-	 * Check whether the header is a valid header for OpenTTD.
-	 * @return true iff the header is deemed valid.
-	 */
 	bool IsValid() const;
 
 	/**
diff --git a/src/livery.h b/src/livery.h
index 8806aff58..7ffa4a644 100644
--- a/src/livery.h
+++ b/src/livery.h
@@ -78,11 +78,6 @@ struct Livery {
 	byte colour2; ///< Second colour, for vehicles with 2CC support.
 };
 
-/**
- * Reset the livery schemes to the company's primary colour.
- * This is used on loading games without livery information and on new company start up.
- * @param c Company to reset.
- */
 void ResetCompanyLivery(Company *c);
 
 #endif /* LIVERY_H */
diff --git a/src/map.cpp b/src/map.cpp
index 70d9cce83..34730028e 100644
--- a/src/map.cpp
+++ b/src/map.cpp
@@ -30,7 +30,7 @@ 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
@@ -97,7 +97,7 @@ TileIndex TileAdd(TileIndex tile, TileIndexDiff add,
 }
 #endif
 
-/*!
+/**
  * 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
@@ -144,7 +144,7 @@ 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.
@@ -161,7 +161,7 @@ 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.
@@ -178,7 +178,7 @@ 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
@@ -193,7 +193,7 @@ 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.
@@ -208,7 +208,7 @@ 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
@@ -224,7 +224,7 @@ uint DistanceFromEdge(TileIndex tile)
 	return min(minl, minh);
 }
 
-/*!
+/**
  * Gets the distance to the edge of the map in given direction.
  * @param tile the tile to get the distance from
  * @param diagdir the direction of interest
@@ -241,7 +241,7 @@ uint DistanceFromEdgeDir(TileIndex tile, DiagDirection dir)
 	}
 }
 
-/*!
+/**
  * Function performing a search around a center tile and going outward, thus in circle.
  * Although it really is a square search...
  * Every tile will be tested by means of the callback function proc,
@@ -273,7 +273,7 @@ bool CircularTileSearch(TileIndex *tile, uint size, TestTileOnSearchProc proc, v
 	}
 }
 
-/*!
+/**
  * Generalized circular search allowing for rectangles and a hole.
  * Function performing a search around a center rectangle and going outward.
  * The center rectangle is left out from the search. To do a rectangular search
@@ -330,7 +330,7 @@ bool CircularTileSearch(TileIndex *tile, uint radius, uint w, uint h, TestTileOn
 	return false;
 }
 
-/*!
+/**
  * Finds the distance for the closest tile with water/land given a tile
  * @param tile  the tile to find the distance too
  * @param water whether to find water or land
diff --git a/src/map_func.h b/src/map_func.h
index e95a223ab..a2b866483 100644
--- a/src/map_func.h
+++ b/src/map_func.h
@@ -43,9 +43,6 @@ extern Tile *_m;
  */
 extern TileExtended *_me;
 
-/**
- * Allocate a new map with the given size.
- */
 void AllocateMap(uint size_x, uint size_y);
 
 /**
@@ -256,9 +253,6 @@ static inline TileIndexDiff ToTileIndexDiff(TileIndexDiffC tidc)
  */
 #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.
- */
 TileIndex TileAddWrap(TileIndex tile, int addx, int addy);
 
 /**
@@ -403,14 +397,7 @@ static inline DiagDirection DiagdirBetweenTiles(TileIndex tile_from, TileIndex t
  */
 typedef bool TestTileOnSearchProc(TileIndex tile, void *user_data);
 
-/**
- * Searches for some cirumstances of a tile around a given tile with a helper function.
- */
 bool CircularTileSearch(TileIndex *tile, uint size, TestTileOnSearchProc proc, void *user_data);
-
-/**
- * Searches for some cirumstances of a tile around a given rectangle with a helper function.
- */
 bool CircularTileSearch(TileIndex *tile, uint radius, uint w, uint h, TestTileOnSearchProc proc, void *user_data);
 
 /**
@@ -431,9 +418,6 @@ static inline TileIndex RandomTileSeed(uint32 r)
  */
 #define RandomTile() RandomTileSeed(Random())
 
-/**
- * Finds the distance for the closest tile with water/land given a tile
- */
 uint GetClosestWaterDistance(TileIndex tile, bool water);
 
 #endif /* MAP_FUNC_H */
diff --git a/src/strings.cpp b/src/strings.cpp
index 948ca5a42..8ef9bc81d 100644
--- a/src/strings.cpp
+++ b/src/strings.cpp
@@ -1383,6 +1383,10 @@ extern void SortNetworkLanguages();
 static inline void SortNetworkLanguages() {}
 #endif /* ENABLE_NETWORK */
 
+/**
+ * Check whether the header is a valid header for OpenTTD.
+ * @return true iff the header is deemed valid.
+ */
 bool LanguagePackHeader::IsValid() const
 {
 	return this->ident        == TO_LE32(LanguagePackHeader::IDENT) &&
diff --git a/src/town_cmd.cpp b/src/town_cmd.cpp
index 32bb0df9f..b043a0450 100644
--- a/src/town_cmd.cpp
+++ b/src/town_cmd.cpp
@@ -157,6 +157,10 @@ void Town::InitializeLayout(TownLayout layout)
 	return Town::Get(index);
 }
 
+/**
+ * Get the cost for removing this house
+ * @return the cost (inflation corrected etc)
+ */
 Money HouseSpec::GetRemovalCost() const
 {
 	return (_price[PR_CLEAR_HOUSE] * this->removal_cost) >> 8;
diff --git a/src/viewport.cpp b/src/viewport.cpp
index f5848a1b9..609709d76 100644
--- a/src/viewport.cpp
+++ b/src/viewport.cpp
@@ -1638,6 +1638,11 @@ void MarkAllViewportsDirty(int left, int top, int right, int bottom)
 	}
 }
 
+/**
+ * Mark a tile given by its index dirty for repaint.
+ * @param tile The tile to mark dirty.
+ * @ingroup dirty
+ */
 void MarkTileDirtyByTile(TileIndex tile)
 {
 	Point pt = RemapCoords(TileX(tile) * TILE_SIZE, TileY(tile) * TILE_SIZE, GetTileZ(tile));