(svn r23704) -Doc: Doxygen comment fixes and additions.

1 files changed, 35 insertions, 7 deletions

diff --git a/src/subsidy.cpp b/src/subsidy.cpp
index 5183b1d2e..1b7362c0a 100644
--- a/src/subsidy.cpp
+++ b/src/subsidy.cpp
@@ -28,7 +28,7 @@
 
 #include "table/strings.h"
 
-SubsidyPool _subsidy_pool("Subsidy");
+SubsidyPool _subsidy_pool("Subsidy"); ///< Pool for the subsidies.
 INSTANTIATE_POOL_METHODS(Subsidy)
 
 /**
@@ -65,6 +65,12 @@ void Subsidy::AwardTo(CompanyID company)
 	InvalidateWindowData(WC_SUBSIDIES_LIST, 0);
 }
 
+/**
+ * Setup the string parameters for printing the subsidy at the screen, and compute the news reference for the subsidy.
+ * @param s %Subsidy being printed.
+ * @param mode Unit of cargo used, \c true means general name, \c false means singular form.
+ * @return Reference of the subsidy in the news system.
+ */
 Pair SetupSubsidyDecodeParam(const Subsidy *s, bool mode)
 {
 	NewsReferenceType reftype1 = NR_NONE;
@@ -121,6 +127,7 @@ static inline void SetPartOfSubsidyFlag(SourceType type, SourceID index, PartOfS
 	}
 }
 
+/** Perform a full rebuild of the subsidies cache. */
 void RebuildSubsidisedSourceAndDestinationCache()
 {
 	Town *t;
@@ -136,6 +143,11 @@ void RebuildSubsidisedSourceAndDestinationCache()
 	}
 }
 
+/**
+ * Delete the subsidies associated with a given cargo source type and id.
+ * @param type  Cargo source type of the id.
+ * @param index Id to remove.
+ */
 void DeleteSubsidyWith(SourceType type, SourceID index)
 {
 	bool dirty = false;
@@ -154,6 +166,15 @@ void DeleteSubsidyWith(SourceType type, SourceID index)
 	}
 }
 
+/**
+ * Check whether a specific subsidy already exists.
+ * @param cargo Cargo type.
+ * @param src_type Type of source of the cargo, affects interpretation of \a src.
+ * @param src Id of the source.
+ * @param dst_type Type of the destination of the cargo, affects interpretation of \a dst.
+ * @param dst Id of the destination.
+ * @return \c true if the subsidy already exists, \c false if not.
+ */
 static bool CheckSubsidyDuplicate(CargoID cargo, SourceType src_type, SourceID src, SourceType dst_type, SourceID dst)
 {
 	const Subsidy *s;
@@ -167,7 +188,8 @@ static bool CheckSubsidyDuplicate(CargoID cargo, SourceType src_type, SourceID s
 	return false;
 }
 
-/** Checks if the source and destination of a subsidy are inside the distance limit.
+/**
+ * Checks if the source and destination of a subsidy are inside the distance limit.
  * @param src_type Type of #src.
  * @param src      Index of source.
  * @param dst_type Type of #dst.
@@ -182,7 +204,8 @@ static bool CheckSubsidyDistance(SourceType src_type, SourceID src, SourceType d
 	return (DistanceManhattan(tile_src, tile_dst) <= SUBSIDY_MAX_DISTANCE);
 }
 
-/** Creates a subsidy with the given parameters.
+/**
+ * Creates a subsidy with the given parameters.
  * @param cid      Subsidised cargo.
  * @param src_type Type of #src.
  * @param src      Index of source.
@@ -266,7 +289,8 @@ CommandCost CmdCreateSubsidy(TileIndex tile, DoCommandFlag flags, uint32 p1, uin
 	return CommandCost();
 }
 
-/** Tries to create a passenger subsidy between two towns.
+/**
+ * Tries to create a passenger subsidy between two towns.
  * @return True iff the subsidy was created.
  */
 bool FindSubsidyPassengerRoute()
@@ -295,7 +319,8 @@ bool FindSubsidyPassengerRoute()
 bool FindSubsidyCargoDestination(CargoID cid, SourceType src_type, SourceID src);
 
 
-/** Tries to create a cargo subsidy with a town as source.
+/**
+ * Tries to create a cargo subsidy with a town as source.
  * @return True iff the subsidy was created.
  */
 bool FindSubsidyTownCargoRoute()
@@ -331,7 +356,8 @@ bool FindSubsidyTownCargoRoute()
 	return FindSubsidyCargoDestination(cid, src_type, src);
 }
 
-/** Tries to create a cargo subsidy with an industry as source.
+/**
+ * Tries to create a cargo subsidy with an industry as source.
  * @return True iff the subsidy was created.
  */
 bool FindSubsidyIndustryCargoRoute()
@@ -368,7 +394,8 @@ bool FindSubsidyIndustryCargoRoute()
 	return FindSubsidyCargoDestination(cid, src_type, src);
 }
 
-/** Tries to find a suitable destination for the given source and cargo.
+/**
+ * Tries to find a suitable destination for the given source and cargo.
  * @param cid      Subsidized cargo.
  * @param src_type Type of #src.
  * @param src      Index of source.
@@ -425,6 +452,7 @@ bool FindSubsidyCargoDestination(CargoID cid, SourceType src_type, SourceID src)
 	return true;
 }
 
+/** Perform the monthly update of open subsidies, and try to create a new one. */
 void SubsidyMonthlyLoop()
 {
 	bool modified = false;