(svn r22460) -Doc: Semantic documentation fixes, and doxygen additions (partly by planetmaker).

src/fileio.cpp

@@ -33,8 +33,10 @@
 /* FILE IO ROUTINES ******************************/
 /*************************************************/
 
+/** Size of the #Fio data buffer. */
 #define FIO_BUFFER_SIZE 512
 
+/** Structure for keeping several open files with just one data buffer. */
 struct Fio {
 	byte *buffer, *buffer_end;             ///< position pointer in local buffer and last valid byte of buffer
 	size_t pos;                            ///< current (system) position in file
@@ -50,7 +52,7 @@ struct Fio {
 #endif /* LIMITED_FDS */
 };
 
-static Fio _fio;
+static Fio _fio; ///< #Fio instance.
 
 /** Whether the working directory should be scanned. */
 static bool _do_scan_working_directory = true;
@@ -58,12 +60,17 @@ static bool _do_scan_working_directory = true;
 extern char *_config_file;
 extern char *_highscore_file;
 
-/* Get current position in file */
+/** Get current position in file. */
 size_t FioGetPos()
 {
 	return _fio.pos + (_fio.buffer - _fio.buffer_end);
 }
 
+/**
+ * Get the filename associated with a slot.
+ * @param slot Index of queried file.
+ * @return Name of the file.
+ */
 const char *FioGetFilename(uint8 slot)
 {
 	return _fio.shortnames[slot];

src/group.h

@@ -7,7 +7,7 @@
  * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
  */
 
-/** @file group.h Base class from groups. */
+/** @file group.h Base class for groups and group functions. */
 
 #ifndef GROUP_H
 #define GROUP_H
@@ -19,12 +19,13 @@
 #include "engine_type.h"
 
 typedef Pool<Group, GroupID, 16, 64000> GroupPool;
-extern GroupPool _group_pool;
+extern GroupPool _group_pool; ///< Pool of groups.
 
+/** Group data. */
 struct Group : GroupPool::PoolItem<&_group_pool> {
 	char *name;                             ///< Group Name
 
-	uint16 num_vehicle;                     ///< Number of vehicles wich belong to the group
+	uint16 num_vehicle;                     ///< Number of vehicles in the group
 	OwnerByte owner;                        ///< Group Owner
 	VehicleTypeByte vehicle_type;           ///< Vehicle type of the group
 
@@ -69,12 +70,20 @@ static inline uint GetGroupArraySize()
 
 uint GetGroupNumEngines(CompanyID company, GroupID id_g, EngineID id_e);
 
+/**
+ * Increase the number of vehicles by one in a group.
+ * @param id_g Group id.
+ */
 static inline void IncreaseGroupNumVehicle(GroupID id_g)
 {
 	Group *g = Group::GetIfValid(id_g);
 	if (g != NULL) g->num_vehicle++;
 }
 
+/**
+ * Decrease the number of vehicles by one in a group.
+ * @param id_g Group id.
+ */
 static inline void DecreaseGroupNumVehicle(GroupID id_g)
 {
 	Group *g = Group::GetIfValid(id_g);

src/openttd.h

@@ -36,14 +36,14 @@ enum SwitchMode {
 	SM_LOAD_HEIGHTMAP,
 };
 
-/* Display Options */
+/** Display Options */
 enum DisplayOptions {
-	DO_SHOW_TOWN_NAMES     = 0,
-	DO_SHOW_STATION_NAMES  = 1,
-	DO_SHOW_SIGNS          = 2,
-	DO_FULL_ANIMATION      = 3,
-	DO_FULL_DETAIL         = 5,
-	DO_SHOW_WAYPOINT_NAMES = 6,
+	DO_SHOW_TOWN_NAMES     = 0, ///< Display town names.
+	DO_SHOW_STATION_NAMES  = 1, ///< Display station names.
+	DO_SHOW_SIGNS          = 2, ///< Display signs.
+	DO_FULL_ANIMATION      = 3, ///< Perform palette animation.
+	DO_FULL_DETAIL         = 5, ///< Also draw details of track and roads.
+	DO_SHOW_WAYPOINT_NAMES = 6, ///< Display waypoint names.
 };
 
 extern GameMode _game_mode;
@@ -59,7 +59,7 @@ enum PauseMode {
 	PM_PAUSED_ERROR          = 1 << 3, ///< A game paused because a (critical) error
 	PM_PAUSED_ACTIVE_CLIENTS = 1 << 4, ///< A game paused for 'min_active_clients'
 
-	/* Pause mode bits when paused for network reasons */
+	/** Pause mode bits when paused for network reasons. */
 	PMB_PAUSED_NETWORK = PM_PAUSED_ACTIVE_CLIENTS | PM_PAUSED_JOIN,
 };
 DECLARE_ENUM_AS_BIT_SET(PauseMode)

src/station_cmd.cpp

@@ -162,7 +162,7 @@ static bool CMSAMine(TileIndex tile)
 /**
  * Check whether the tile is water.
  * @param tile the tile to investigate.
- * @return true if and only if the tile is a mine
+ * @return true if and only if the tile is a water tile
  */
 static bool CMSAWater(TileIndex tile)
 {
@@ -172,7 +172,7 @@ static bool CMSAWater(TileIndex tile)
 /**
  * Check whether the tile is a tree.
  * @param tile the tile to investigate.
- * @return true if and only if the tile is a mine
+ * @return true if and only if the tile is a tree tile
  */
 static bool CMSATree(TileIndex tile)
 {
@@ -182,7 +182,7 @@ static bool CMSATree(TileIndex tile)
 /**
  * Check whether the tile is a forest.
  * @param tile the tile to investigate.
- * @return true if and only if the tile is a mine
+ * @return true if and only if the tile is a forest
  */
 static bool CMSAForest(TileIndex tile)
 {