(svn r22411) -Document: another bunch of bits

src/core/endian_type.hpp

@@ -13,12 +13,16 @@
 #define ENDIAN_TYPE_HPP
 
 #if defined(ARM) || defined(__arm__) || defined(__alpha__)
+	/** The architecture requires aligned access. */
 	#define OTTD_ALIGNMENT 1
 #else
+	/** The architecture does not require aligned access. */
 	#define OTTD_ALIGNMENT 0
 #endif
 
+/** Little endian builds use this for TTD_ENDIAN. */
 #define TTD_LITTLE_ENDIAN 0
+/** Big endian builds use this for TTD_ENDIAN. */
 #define TTD_BIG_ENDIAN 1
 
 /* Windows has always LITTLE_ENDIAN */

src/core/pool_func.hpp

@@ -16,6 +16,10 @@
 #include "mem_func.hpp"
 #include "pool_type.hpp"
 
+/**
+ * Helper for defining the method's signature.
+ * @param type The return type of the method.
+ */
 #define DEFINE_POOL_METHOD(type) \
 	template <class Titem, typename Tindex, size_t Tgrowth_step, size_t Tmax_size, PoolType Tpool_type, bool Tcache, bool Tzero> \
 	type Pool<Titem, Tindex, Tgrowth_step, Tmax_size, Tpool_type, Tcache, Tzero>

src/core/smallvec_type.hpp

@@ -35,12 +35,20 @@ protected:
 public:
 	SmallVector() : data(NULL), items(0), capacity(0) { }
 
+	/**
+	 * Copy constructor.
+	 * @param other The other vector to copy.
+	 */
 	template <uint X>
 	SmallVector(const SmallVector<T, X> &other) : data(NULL), items(0), capacity(0)
 	{
 		MemCpyT<T>(this->Append(other.Length()), other.Begin(), other.Length());
 	}
 
+	/**
+	 * Assignment.
+	 * @param other The new vector that.
+	 */
 	template <uint X>
 	SmallVector &operator=(const SmallVector<T, X> &other)
 	{
@@ -318,6 +326,6 @@ public:
 	}
 };
 
-typedef AutoFreeSmallVector<char*, 4> StringList;
+typedef AutoFreeSmallVector<char*, 4> StringList; ///< Type for a list of strings.
 
 #endif /* SMALLVEC_TYPE_HPP */

src/core/string_compare_type.hpp

@@ -12,7 +12,14 @@
 #ifndef STRING_COMPARE_TYPE_HPP
 #define STRING_COMPARE_TYPE_HPP
 
+/** Comparator for strings. */
 struct StringCompare {
+	/**
+	 * Compare two strings.
+	 * @param a The first string.
+	 * @param b The second string.
+	 * @return True is the first string is deemed "lower" than the second string.
+	 */
 	bool operator () (const char *a, const char *b) const
 	{
 		return strcmp(a, b) < 0;

src/currency.cpp

@@ -22,6 +22,7 @@
 	 *   |  separator        |           postfix             |
 	 *   |   |   Euro year   |              |                | name
 	 *   |   |    |          |              |                |  | */
+/** The original currency specifications. */
 static const CurrencySpec origin_currency_specs[NUM_CURRENCY] = {
 	{    1, "", CF_NOEURO, "\xC2\xA3",     "",              0, STR_GAME_OPTIONS_CURRENCY_GBP    }, ///< british pounds
 	{    2, "", CF_NOEURO, "$",            "",              0, STR_GAME_OPTIONS_CURRENCY_USD    }, ///< us dollars
@@ -54,7 +55,7 @@ static const CurrencySpec origin_currency_specs[NUM_CURRENCY] = {
 	{    1, "", CF_NOEURO, "",             "",              2, STR_GAME_OPTIONS_CURRENCY_CUSTOM }, ///< custom currency
 };
 
-/* Array of currencies used by the system */
+/** Array of currencies used by the system */
 CurrencySpec _currency_specs[NUM_CURRENCY];
 
 /**

src/date.cpp

@@ -23,7 +23,7 @@
 Year      _cur_year;   ///< Current year, starting at 0
 Month     _cur_month;  ///< Current month (0..11)
 Date      _date;       ///< Current date in days (day counter)
-DateFract _date_fract;
+DateFract _date_fract; ///< Fractional part of the day.
 uint16 _tick_counter;  ///< Ever incrementing (and sometimes wrapping) tick counter for setting off various events
 
 /**

src/date_func.h

@@ -24,6 +24,11 @@ void SetDate(Date date, DateFract fract);
 void ConvertDateToYMD(Date date, YearMonthDay *ymd);
 Date ConvertYMDToDate(Year year, Month month, Day day);
 
+/**
+ * Checks whether the given year is a leap year or not.
+ * @param yr The year to check.
+ * @return True if \c yr is a leap year, otherwise false.
+ */
 static inline bool IsLeapYear(Year yr)
 {
 	return yr % 4 == 0 && (yr % 100 != 0 || yr % 400 == 0);

src/date_gui.cpp

@@ -181,6 +181,7 @@ struct SetDateWindow : Window {
 	}
 };
 
+/** Widgets for the date setting window. */
 static const NWidgetPart _nested_set_date_widgets[] = {
 	NWidget(NWID_HORIZONTAL),
 		NWidget(WWT_CLOSEBOX, COLOUR_BROWN),
@@ -202,6 +203,7 @@ static const NWidgetPart _nested_set_date_widgets[] = {
 	EndContainer()
 };
 
+/** Description of the date setting window. */
 static const WindowDesc _set_date_desc(
 	WDP_CENTER, 0, 0,
 	WC_SET_DATE, WC_NONE,

src/depend/depend.cpp

@@ -31,6 +31,7 @@
 #include <stack>
 
 #ifndef PATH_MAX
+/** The maximum length of paths, if we don't know it. */
 #	define PATH_MAX 260
 #endif
 

src/depot.cpp

@@ -18,6 +18,7 @@
 #include "vehicle_gui.h"
 #include "vehiclelist.h"
 
+/** All our depots tucked away in a pool. */
 DepotPool _depot_pool("Depot");
 INSTANTIATE_POOL_METHODS(Depot)
 

src/depot_cmd.cpp

@@ -21,7 +21,11 @@
 
 #include "table/strings.h"
 
-
+/**
+ * Check whether the given name is globally unique amongst depots.
+ * @param name The name to check.
+ * @return True if there is no depot with the given name.
+ */
 static bool IsUniqueDepotName(const char *name)
 {
 	const Depot *d;

src/depot_type.h

@@ -12,7 +12,7 @@
 #ifndef DEPOT_TYPE_H
 #define DEPOT_TYPE_H
 
-typedef uint16 DepotID;
+typedef uint16 DepotID; ///< Type for the unique identifier of depots.
 struct Depot;
 
 static const uint MAX_LENGTH_DEPOT_NAME_CHARS = 32; ///< The maximum length of a depot name in characters including '\0'

src/direction_type.h

@@ -42,7 +42,7 @@ DECLARE_POSTFIX_INCREMENT(Direction)
 
 /** Define basic enum properties */
 template <> struct EnumPropsT<Direction> : MakeEnumPropsT<Direction, byte, DIR_BEGIN, DIR_END, INVALID_DIR, 3> {};
-typedef TinyEnumT<Direction> DirectionByte; // typedefing-enumification of Direction
+typedef TinyEnumT<Direction> DirectionByte; ///< typedefing-enumification of Direction
 
 
 /**
@@ -92,7 +92,7 @@ DECLARE_POSTFIX_INCREMENT(DiagDirection)
 
 /** Define basic enum properties */
 template <> struct EnumPropsT<DiagDirection> : MakeEnumPropsT<DiagDirection, byte, DIAGDIR_BEGIN, DIAGDIR_END, INVALID_DIAGDIR, 2> {};
-typedef TinyEnumT<DiagDirection> DiagDirectionByte; // typedefing-enumification of DiagDirection
+typedef TinyEnumT<DiagDirection> DiagDirectionByte; ///< typedefing-enumification of DiagDirection
 
 
 /**
@@ -130,6 +130,7 @@ enum Axis {
 	AXIS_END,            ///< Used for iterations
 	INVALID_AXIS = 0xFF, ///< Flag for an invalid Axis
 };
+/** Helper information for extract tool. */
 template <> struct EnumPropsT<Axis> : MakeEnumPropsT<Axis, byte, AXIS_X, AXIS_END, INVALID_AXIS, 1> {};
 
 #endif /* DIRECTION_TYPE_H */

src/economy_base.h

@@ -48,7 +48,17 @@ struct CargoPayment : CargoPaymentPool::PoolItem<&_cargo_payment_pool> {
 	void SetCargo(CargoID ct) { this->ct = ct; }
 };
 
+/**
+ * Iterate over all cargo payments from a given start position.
+ * @param var The variable used for iterating.
+ * @param start The start of the iteration.
+ */
 #define FOR_ALL_CARGO_PAYMENTS_FROM(var, start) FOR_ALL_ITEMS_FROM(CargoPayment, cargo_payment_index, var, start)
+
+/**
+ * Iterate over all cargo payments.
+ * @param var The variable used for iterating.
+ */
 #define FOR_ALL_CARGO_PAYMENTS(var) FOR_ALL_CARGO_PAYMENTS_FROM(var, 0)
 
 #endif /* ECONOMY_BASE_H */

src/effectvehicle.cpp

@@ -558,6 +558,14 @@ static EffectTickProc * const _effect_tick_procs[] = {
 };
 
 
+/**
+ * Create an effect vehicle at a particular location.
+ * @param x The x location on the map.
+ * @param y The y location on the map.
+ * @param z The z location on the map.
+ * @param type The type of effect vehicle.
+ * @return The effect vehicle.
+ */
 EffectVehicle *CreateEffectVehicle(int x, int y, int z, EffectVehicleType type)
 {
 	if (!Vehicle::CanAllocateItem()) return NULL;
@@ -579,6 +587,14 @@ EffectVehicle *CreateEffectVehicle(int x, int y, int z, EffectVehicleType type)
 	return v;
 }
 
+/**
+ * Create an effect vehicle above a particular location.
+ * @param x The x location on the map.
+ * @param y The y location on the map.
+ * @param z The offset from the ground.
+ * @param type The type of effect vehicle.
+ * @return The effect vehicle.
+ */
 EffectVehicle *CreateEffectVehicleAbove(int x, int y, int z, EffectVehicleType type)
 {
 	int safe_x = Clamp(x, 0, MapMaxX() * TILE_SIZE);
@@ -586,6 +602,15 @@ EffectVehicle *CreateEffectVehicleAbove(int x, int y, int z, EffectVehicleType t
 	return CreateEffectVehicle(x, y, GetSlopeZ(safe_x, safe_y) + z, type);
 }
 
+/**
+ * Create an effect vehicle above a particular vehicle.
+ * @param v The vehicle to base the position on.
+ * @param x The x offset to the vehicle.
+ * @param y The y offset to the vehicle.
+ * @param z The z offset to the vehicle.
+ * @param type The type of effect vehicle.
+ * @return The effect vehicle.
+ */
 EffectVehicle *CreateEffectVehicleRel(const Vehicle *v, int x, int y, int z, EffectVehicleType type)
 {
 	return CreateEffectVehicle(v->x_pos + x, v->y_pos + y, v->z_pos + z, type);

src/elrail.cpp

@@ -67,6 +67,11 @@
 
 #include "table/elrail_data.h"
 
+/**
+ * Get the tile location group of a tile.
+ * @param t The tile to get the tile location group of.
+ * @return The tile location group.
+ */
 static inline TLG GetTLG(TileIndex t)
 {
 	return (TLG)((HasBit(TileX(t), 0) << 1) + HasBit(TileY(t), 0));

src/engine.cpp

@@ -614,6 +614,11 @@ void SetYearEngineAgingStops()
 	}
 }
 
+/**
+ * Start/initialise one engine.
+ * @param e The engine to initialise.
+ * @param aging_date The date used for age calculations.
+ */
 void StartupOneEngine(Engine *e, Date aging_date)
 {
 	const EngineInfo *ei = &e->info;
@@ -654,6 +659,7 @@ void StartupOneEngine(Engine *e, Date aging_date)
 	}
 }
 
+/** Start/initialise all our engines. */
 void StartupEngines()
 {
 	Engine *e;

src/engine_gui.cpp

@@ -128,6 +128,11 @@ void ShowEnginePreviewWindow(EngineID engine)
 	AllocateWindowDescFront<EnginePreviewWindow>(&_engine_preview_desc, engine);
 }
 
+/**
+ * Get the capacity of an engine with articulated parts.
+ * @param engine The engine to get the capacity of.
+ * @return The capacity.
+ */
 uint GetTotalCapacityOfArticulatedParts(EngineID engine)
 {
 	uint total = 0;

src/gamelog.cpp

@@ -326,6 +326,7 @@ static void GamelogPrintConsoleProc(const char *s)
 	IConsolePrint(CC_WARNING, s);
 }
 
+/** Print the gamelog data to the console. */
 void GamelogPrintConsole()
 {
 	GamelogPrint(&GamelogPrintConsoleProc);

src/gamelog.h

@@ -14,6 +14,7 @@
 
 #include "newgrf_config.h"
 
+/** The actions we log. */
 enum GamelogActionType {
 	GLAT_START,        ///< Game created
 	GLAT_LOAD,         ///< Game loaded
@@ -31,6 +32,10 @@ void GamelogStopAction();
 
 void GamelogReset();
 
+/**
+ * Callback for printing text.
+ * @param s The string to print.
+ */
 typedef void GamelogPrintProc(const char *s);
 void GamelogPrint(GamelogPrintProc *proc); // needed for WIN32 / WINCE crash.log
 

src/genworld_gui.cpp

@@ -875,21 +875,28 @@ static void _ShowGenerateLandscape(GenenerateLandscapeWindowMode mode)
 	SetWindowDirty(WC_GENERATE_LANDSCAPE, mode);
 }
 
+/** Start with a normal game. */
 void ShowGenerateLandscape()
 {
 	_ShowGenerateLandscape(GLWM_GENERATE);
 }
 
+/** Start with loading a heightmap. */
 void ShowHeightmapLoad()
 {
 	_ShowGenerateLandscape(GLWM_HEIGHTMAP);
 }
 
+/** Start with a scenario editor. */
 void StartScenarioEditor()
 {
 	StartGeneratingLandscape(GLWM_SCENARIO);
 }
 
+/**
+ * Start a normal game without the GUI.
+ * @param seed The seed of the new game.
+ */
 void StartNewGameWithoutGUI(uint seed)
 {
 	/* GenerateWorld takes care of the possible GENERATE_NEW_SEED value in 'seed' */
@@ -1155,6 +1162,7 @@ static const WindowDesc _create_scenario_desc(
 	_nested_create_scenario_widgets, lengthof(_nested_create_scenario_widgets)
 );
 
+/** Show the window to create a scenario. */
 void ShowCreateScenario()
 {
 	DeleteWindowByClass(WC_GENERATE_LANDSCAPE);

src/gfxinit.cpp

@@ -135,7 +135,7 @@ void CheckExternalFiles()
 	if (add_pos != error_msg) ShowInfoF("%s", error_msg);
 }
 
-
+/** Actually load the sprite tables. */
 static void LoadSpriteTables()
 {
 	memset(_palette_remap_grf, 0, sizeof(_palette_remap_grf));
@@ -199,6 +199,7 @@ static void LoadSpriteTables()
 }
 
 
+/** Initialise and load all the sprites. */
 void GfxLoadSprites()
 {
 	DEBUG(sprite, 2, "Loading sprite set %d", _settings_game.game_creation.landscape);

src/group_gui.cpp

@@ -661,6 +661,11 @@ static const WindowDesc _train_group_desc(
 	_nested_group_widgets, lengthof(_nested_group_widgets)
 );
 
+/**
+ * Show the group window for the given company and vehicle type.
+ * @param company The company to show the window for.
+ * @param vehicle_type The type of vehicle to show it for.
+ */
 void ShowCompanyGroup(CompanyID company, VehicleType vehicle_type)
 {
 	if (!Company::IsValidID(company)) return;

src/group_type.h

@@ -12,11 +12,11 @@
 #ifndef GROUP_TYPE_H
 #define GROUP_TYPE_H
 
-typedef uint16 GroupID;
+typedef uint16 GroupID; ///< Type for all group identifiers.
 
-static const GroupID ALL_GROUP     = 0xFFFD;
-static const GroupID DEFAULT_GROUP = 0xFFFE; ///< ungrouped vehicles are in this group.
-static const GroupID INVALID_GROUP = 0xFFFF;
+static const GroupID ALL_GROUP     = 0xFFFD; ///< All vehicles are in this group.
+static const GroupID DEFAULT_GROUP = 0xFFFE; ///< Ungrouped vehicles are in this group.
+static const GroupID INVALID_GROUP = 0xFFFF; ///< Sentinel for invalid groups.
 
 static const uint MAX_LENGTH_GROUP_NAME_CHARS = 32; ///< The maximum length of a group name in characters including '\0'
 

src/house_type.h

@@ -12,8 +12,8 @@
 #ifndef HOUSE_TYPE_H
 #define HOUSE_TYPE_H
 
-typedef uint16 HouseID;
-typedef uint16 HouseClassID;
+typedef uint16 HouseID; ///< OpenTTD ID of house types.
+typedef uint16 HouseClassID; ///< Classes of houses.
 
 struct HouseSpec;
 

src/ini.cpp

@@ -25,6 +25,10 @@
 # include "core/mem_func.hpp"
 #endif
 
+/**
+ * Create a new ini file with given group names.
+ * @param list_group_names A \c NULL terminated list with group names that should be loaded as lists instead of variables. @see IGT_LIST
+ */
 IniFile::IniFile(const char * const *list_group_names) : IniLoadFile(list_group_names)
 {
 }

src/language.h

@@ -85,6 +85,7 @@ struct LanguagePackHeader {
 		return MAX_NUM_CASES;
 	}
 };
+/** Make sure the size is right. */
 assert_compile(sizeof(LanguagePackHeader) % 4 == 0);
 
 /** Metadata about a single language. */

src/livery.h

@@ -59,6 +59,7 @@ enum LiveryScheme {
 };
 
 DECLARE_POSTFIX_INCREMENT(LiveryScheme)
+/** Helper information for extract tool. */
 template <> struct EnumPropsT<LiveryScheme> : MakeEnumPropsT<LiveryScheme, byte, LS_BEGIN, LS_END, LS_END, 8> {};
 
 /** List of different livery classes, used only by the livery GUI. */
@@ -71,7 +72,7 @@ enum LiveryClass {
 	LC_END
 };
 
-
+/** Information about a particular livery. */
 struct Livery {
 	bool in_use;  ///< Set if this livery should be used instead of the default livery.
 	byte colour1; ///< First colour, for all vehicles.

src/map.cpp

@@ -228,7 +228,7 @@ uint DistanceFromEdge(TileIndex tile)
 /**
  * Gets the distance to the edge of the map in given direction.
  * @param tile the tile to get the distance from
- * @param diagdir the direction of interest
+ * @param dir the direction of interest
  * @return the distance from the edge in tiles
  */
 uint DistanceFromEdgeDir(TileIndex tile, DiagDirection dir)

src/map_func.h

@@ -187,6 +187,12 @@ static inline TileIndexDiff TileDiffXY(int x, int y)
 	return (y * MapSizeX()) + x;
 }
 
+/**
+ * Get a tile from the virtual XY-coordinate.
+ * @param x The virtual x coordinate of the tile.
+ * @param y The virtual y coordinate of the tile.
+ * @return The TileIndex calculated by the coordinate.
+ */
 static inline TileIndex TileVirtXY(uint x, uint y)
 {
 	return (y >> 4 << MapLogX()) + (x >> 4);

src/misc/array.hpp

@@ -76,6 +76,10 @@ public:
 		return item;
 	}
 
+	/**
+	 * Helper for creating a human readable output of this data.
+	 * @param dmp The location to dump to.
+	 */
 	template <typename D> void Dump(D &dmp) const
 	{
 		dmp.WriteLine("capacity = %d", Tcapacity);

src/misc/binaryheap.hpp

@@ -14,12 +14,14 @@
 
 #include "../core/alloc_func.hpp"
 
-/* Enable it if you suspect binary heap doesn't work well */
+/** Enable it if you suspect binary heap doesn't work well */
 #define BINARYHEAP_CHECK 0
 
 #if BINARYHEAP_CHECK
+	/** Check for consistency. */
 	#define CHECK_CONSISTY() this->CheckConsistency()
 #else
+	/** Don't check for consistency. */
 	#define CHECK_CONSISTY() ;
 #endif
 
@@ -55,6 +57,10 @@ private:
 	T **data;      ///< The pointer to the heap item pointers
 
 public:
+	/**
+	 * Create a binary heap.
+	 * @param max_items The limit of the heap
+	 */
 	explicit CBinaryHeapT(uint max_items)
 		: items(0)
 		, capacity(max_items)

src/misc/fixedsizearray.hpp

@@ -31,8 +31,8 @@ protected:
 	};
 
 	/* make constants visible from outside */
-	static const uint Tsize = sizeof(T);                // size of item
-	static const uint HeaderSize = sizeof(ArrayHeader); // size of header
+	static const uint Tsize = sizeof(T);                ///< size of item
+	static const uint HeaderSize = sizeof(ArrayHeader); ///< size of header
 
 	/**
 	 * the only member of fixed size array is pointer to the block

src/strings.cpp

@@ -1476,6 +1476,11 @@ bool LanguagePackHeader::IsValid() const
 	       StrValid(this->digit_decimal_separator,        lastof(this->digit_decimal_separator));
 }
 
+/**
+ * Read a particular language.
+ * @param lang The metadata about the language.
+ * @return Whether the loading went okay or not.
+ */
 bool ReadLanguagePack(const LanguageMetadata *lang)
 {
 	/* Current language pack */