(svn r21846) -Codechange: move documentation towards the code to make it more likely to be updated [o-s].

1 files changed, 31 insertions, 0 deletions

diff --git a/src/rail.cpp b/src/rail.cpp
index 2a308c547..13346d607 100644
--- a/src/rail.cpp
+++ b/src/rail.cpp
@@ -149,6 +149,9 @@ extern const TrackdirBits _uphill_trackdirs[] = {
 	TRACKDIR_BIT_X_NE | TRACKDIR_BIT_Y_SE, ///< 30 SLOPE_STEEP_E -> inclined for diagonal track
 };
 
+/**
+ * Return the rail type of tile, or INVALID_RAILTYPE if this is no rail tile.
+ */
 RailType GetTileRailType(TileIndex tile)
 {
 	switch (GetTileType(tile)) {
@@ -174,16 +177,34 @@ RailType GetTileRailType(TileIndex tile)
 	return INVALID_RAILTYPE;
 }
 
+/**
+ * Finds out if a company has a certain railtype available
+ * @param company the company in question
+ * @param railtype requested RailType
+ * @return true if company has requested RailType available
+ */
 bool HasRailtypeAvail(const CompanyID company, const RailType railtype)
 {
 	return HasBit(Company::Get(company)->avail_railtypes, railtype);
 }
 
+/**
+ * Validate functions for rail building.
+ * @param rail the railtype to check.
+ * @return true if the current company may build the rail.
+ */
 bool ValParamRailtype(const RailType rail)
 {
 	return rail < RAILTYPE_END && HasRailtypeAvail(_current_company, rail);
 }
 
+/**
+ * Returns the "best" railtype a company can build.
+ * As the AI doesn't know what the BEST one is, we have our own priority list
+ * here. When adding new railtypes, modify this function
+ * @param company the company "in action"
+ * @return The "best" railtype a company has available
+ */
 RailType GetBestRailtype(const CompanyID company)
 {
 	if (HasRailtypeAvail(company, RAILTYPE_MAGLEV)) return RAILTYPE_MAGLEV;
@@ -226,6 +247,11 @@ RailTypes AddDateIntroducedRailTypes(RailTypes current, Date date)
 	return rts == current ? rts : AddDateIntroducedRailTypes(rts, date);
 }
 
+/**
+ * Get the rail types the given company can build.
+ * @param c the company to get the rail types for.
+ * @return the rail types.
+ */
 RailTypes GetCompanyRailtypes(CompanyID company)
 {
 	RailTypes rts = RAILTYPES_NONE;
@@ -248,6 +274,11 @@ RailTypes GetCompanyRailtypes(CompanyID company)
 	return AddDateIntroducedRailTypes(rts, _date);
 }
 
+/**
+ * Get the rail type for a given label.
+ * @param label the railtype label.
+ * @return the railtype.
+ */
 RailType GetRailTypeByLabel(RailTypeLabel label)
 {
 	/* Loop through each rail type until the label is found */