(svn r19482) -Doc: Doxygen additions/updates.

src/town_cmd.cpp

@@ -2677,7 +2677,13 @@ CommandCost CheckIfAuthorityAllowsNewStation(TileIndex tile, DoCommandFlag flags
 	return_cmd_error(STR_ERROR_LOCAL_AUTHORITY_REFUSES_TO_ALLOW_THIS);
 }
 
-
+/** Return the town closest to the given tile within \a threshold.
+ * @param tile      Starting point of the search.
+ * @param threshold Biggest allowed distance to the town.
+ * @return Closest town to \a tile withinh \a threshold, or \c NULL if there is no such town.
+ *
+ * @note This function only uses distance, the #ClosestTownFromTile function also takes town ownership into account.
+ */
 Town *CalcClosestTownFromTile(TileIndex tile, uint threshold)
 {
 	Town *t;

src/tunnelbridge_cmd.cpp

@@ -66,8 +66,10 @@ void ResetBridges()
 	memcpy(&_bridge, &_orig_bridge, sizeof(_orig_bridge));
 }
 
-/** calculate the price factor for building a long bridge.
+/** Calculate the price factor for building a long bridge.
- * basically the cost delta is 1,1, 1, 2,2, 3,3,3, 4,4,4,4, 5,5,5,5,5, 6,6,6,6,6,6,  7,7,7,7,7,7,7,  8,8,8,8,8,8,8,8,
+ * Basically the cost delta is 1,1, 1, 2,2, 3,3,3, 4,4,4,4, 5,5,5,5,5, 6,6,6,6,6,6,  7,7,7,7,7,7,7,  8,8,8,8,8,8,8,8,
+ * @param length Length of the bridge.
+ * @return Price factor for the bridge.
  */
 int CalcBridgeLenCostFactor(int x)
 {
@@ -630,6 +632,11 @@ static inline CommandCost CheckAllowRemoveTunnelBridge(TileIndex tile)
 	}
 }
 
+/** Remove a tunnel from the game, update town rating, etc.
+ * @param tile Tile containing one of the endpoints of the tunnel.
+ * @param flags Command flags.
+ * @return Succeeded or failed command.
+ */
 static CommandCost DoClearTunnel(TileIndex tile, DoCommandFlag flags)
 {
 	Town *t = NULL;
@@ -696,6 +703,11 @@ static CommandCost DoClearTunnel(TileIndex tile, DoCommandFlag flags)
 }
 
 
+/** Remove a bridge from the game, update town rating, etc.
+ * @param tile Tile containing one of the endpoints of the bridge.
+ * @param flags Command flags.
+ * @return Succeeded or failed command.
+ */
 static CommandCost DoClearBridge(TileIndex tile, DoCommandFlag flags)
 {
 	DiagDirection direction;
@@ -772,6 +784,11 @@ static CommandCost DoClearBridge(TileIndex tile, DoCommandFlag flags)
 	return CommandCost(EXPENSES_CONSTRUCTION, (GetTunnelBridgeLength(tile, endtile) + 2) * _price[PR_CLEAR_BRIDGE]);
 }
 
+/** Remove a tunnel or a bridge from the game.
+ * @param tile Tile containing one of the endpoints.
+ * @param flags Command flags.
+ * @return Succeeded or failed command.
+ */
 static CommandCost ClearTile_TunnelBridge(TileIndex tile, DoCommandFlag flags)
 {
 	if (IsTunnel(tile)) {

src/vehicle_cmd.cpp

@@ -274,7 +274,7 @@ static CommandCost GetRefitCost(EngineID engine_type)
  * @param new_cid      Cargotype to refit to
  * @param new_subtype  Cargo subtype to refit to
  * @param flags        Command flags
- * @return refit cost; or CMD_ERROR if no vehicle was actually refitable to the cargo
+ * @return Refit cost.
  */
 CommandCost RefitVehicle(Vehicle *v, bool only_this, CargoID new_cid, byte new_subtype, DoCommandFlag flags)
 {