(svn r10764) -Documentation: [FS#1099]: of road.h. Based on a patch by Progman.

1 files changed, 75 insertions, 25 deletions

diff --git a/src/road.h b/src/road.h
index acb958246..3a6ce33ea 100644
--- a/src/road.h
+++ b/src/road.h
@@ -9,30 +9,31 @@
 
 /**
  * The different roadtypes we support
- * @note currently only ROADTYPE_ROAD is supported.
+ *
+ * @note currently only ROADTYPE_ROAD and ROADTYPE_TRAM are supported.
  */
 enum RoadType {
-	ROADTYPE_ROAD = 0,
-	ROADTYPE_TRAM = 1,
-	ROADTYPE_HWAY = 2, ///< Only a placeholder. Not sure what we are going to do with this road type.
-	ROADTYPE_END,
-	INVALID_ROADTYPE = 0xFF
+	ROADTYPE_ROAD = 0,      ///< Basic road type
+	ROADTYPE_TRAM = 1,      ///< Trams
+	ROADTYPE_HWAY = 2,      ///< Only a placeholder. Not sure what we are going to do with this road type.
+	ROADTYPE_END,           ///< Used for iterations
+	INVALID_ROADTYPE = 0xFF ///< flag for invalid roadtype
 };
 DECLARE_POSTFIX_INCREMENT(RoadType);
 
 /**
  * The different roadtypes we support, but then a bitmask of them
- * @note currently only ROADTYPES_ROAD is supported.
+ * @note currently only roadtypes with ROADTYPE_ROAD and ROADTYPE_TRAM are supported.
  */
 enum RoadTypes {
-	ROADTYPES_NONE     = 0,
-	ROADTYPES_ROAD     = 1 << ROADTYPE_ROAD,
-	ROADTYPES_TRAM     = 1 << ROADTYPE_TRAM,
-	ROADTYPES_HWAY     = 1 << ROADTYPE_HWAY,
-	ROADTYPES_ROADTRAM = ROADTYPES_ROAD | ROADTYPES_TRAM,
-	ROADTYPES_ROADHWAY = ROADTYPES_ROAD | ROADTYPES_HWAY,
-	ROADTYPES_TRAMHWAY = ROADTYPES_TRAM | ROADTYPES_HWAY,
-	ROADTYPES_ALL      = ROADTYPES_ROAD | ROADTYPES_TRAM | ROADTYPES_HWAY,
+	ROADTYPES_NONE     = 0,                                                 ///< No roadtypes
+	ROADTYPES_ROAD     = 1 << ROADTYPE_ROAD,                                ///< Road
+	ROADTYPES_TRAM     = 1 << ROADTYPE_TRAM,                                ///< Trams
+	ROADTYPES_HWAY     = 1 << ROADTYPE_HWAY,                                ///< Highway (or whatever substitute)
+	ROADTYPES_ROADTRAM = ROADTYPES_ROAD | ROADTYPES_TRAM,                   ///< Road + trams
+	ROADTYPES_ROADHWAY = ROADTYPES_ROAD | ROADTYPES_HWAY,                   ///< Road + highway (or whatever substitute)
+	ROADTYPES_TRAMHWAY = ROADTYPES_TRAM | ROADTYPES_HWAY,                   ///< Trams + highway (or whatever substitute)
+	ROADTYPES_ALL      = ROADTYPES_ROAD | ROADTYPES_TRAM | ROADTYPES_HWAY,  ///< Road + trams + highway (or whatever substitute)
 };
 DECLARE_ENUM_AS_BIT_SET(RoadTypes);
 
@@ -58,47 +59,91 @@ static inline bool AreValidRoadTypes(RoadTypes rts)
 
 /**
  * Maps a RoadType to the corresponding RoadTypes value
+ *
+ * @param rt the roadtype to get the roadtypes from
+ * @return the roadtypes with the given roadtype
  */
 static inline RoadTypes RoadTypeToRoadTypes(RoadType rt)
 {
 	return (RoadTypes)(1 << rt);
 }
 
+/**
+ * Returns the RoadTypes which are not present in the given RoadTypes
+ *
+ * This function returns the complement of a given RoadTypes.
+ *
+ * @param r The given RoadTypes
+ * @return The complement of the given RoadTypes
+ * @note The unused value ROADTYPES_HWAY will be used, too.
+ */
 static inline RoadTypes ComplementRoadTypes(RoadTypes r)
 {
 	return (RoadTypes)(ROADTYPES_ALL ^ r);
 }
 
+/**
+ * Enumeration for the road parts on a tile.
+ *
+ * This enumeration defines the possible road parts which
+ * can be build on a tile.
+ */
 enum RoadBits {
-	ROAD_NONE = 0U,
-	ROAD_NW  = 1U,
-	ROAD_SW  = 2U,
-	ROAD_SE  = 4U,
-	ROAD_NE  = 8U,
-	ROAD_X   = ROAD_SW | ROAD_NE,
-	ROAD_Y   = ROAD_NW | ROAD_SE,
-	ROAD_ALL = ROAD_X  | ROAD_Y
+	ROAD_NONE = 0U,                  ///< No road-part is build
+	ROAD_NW   = 1U,                  ///< North-west part
+	ROAD_SW   = 2U,                  ///< South-west part
+	ROAD_SE   = 4U,                  ///< South-east part
+	ROAD_NE   = 8U,                  ///< North-east part
+	ROAD_X    = ROAD_SW | ROAD_NE,   ///< Full road along the x-axis (south-west + north-east)
+	ROAD_Y    = ROAD_NW | ROAD_SE,   ///< Full road along the y-axis (north-west + south-east)
+	ROAD_ALL  = ROAD_X  | ROAD_Y     ///< Full 4-way crossing
 };
 
 DECLARE_ENUM_AS_BIT_SET(RoadBits);
 
+/**
+ * Calculate the complement of a RoadBits value
+ *
+ * Simply flips all bits in the RoadBits value to get the complement
+ * of the RoadBits.
+ *
+ * @param r The given RoadBits value
+ * @return the complement
+ */
 static inline RoadBits ComplementRoadBits(RoadBits r)
 {
 	return (RoadBits)(ROAD_ALL ^ r);
 }
 
+/**
+ * Create the road-part which belongs to the given DiagDirection
+ *
+ * This function returns a RoadBits value which belongs to
+ * the given DiagDirection.
+ *
+ * @param d The DiagDirection
+ * @return The result RoadBits which the selected road-part set
+ */
 static inline RoadBits DiagDirToRoadBits(DiagDirection d)
 {
 	return (RoadBits)(1U << (3 ^ d));
 }
 
-/** Checks whether the trackdir means that we are reversing */
+/**
+ * Checks whether the trackdir means that we are reversing.
+ * @param dir the trackdir to check
+ * @return true if it is a reversing road trackdir
+ */
 static inline bool IsReversingRoadTrackdir(Trackdir dir)
 {
 	return (dir & 0x07) >= 6;
 }
 
-/** Checks whether the given trackdir is a straight road */
+/**
+ * Checks whether the given trackdir is a straight road
+ * @param dir the trackdir to check
+ * @return true if it is a straight road trackdir
+ */
 static inline bool IsStraightRoadTrackdir(Trackdir dir)
 {
 	return (dir & 0x06) == 0;
@@ -115,6 +160,11 @@ static inline bool IsStraightRoadTrackdir(Trackdir dir)
  */
 bool CheckAllowRemoveRoad(TileIndex tile, RoadBits remove, Owner owner, bool *edge_road, RoadType rt);
 
+/**
+ * Draw the catenary for tram road bits
+ * @param ti   information about the tile (position, slope)
+ * @param tram the roadbits to draw the catenary for
+ */
 void DrawTramCatenary(TileInfo *ti, RoadBits tram);
 
 #endif /* ROAD_H */