(svn r22406) -Document: some more "random-ish" tidbits

Doxyfile

@@ -195,7 +195,7 @@ EXPAND_ONLY_PREDEF     = YES
 SEARCH_INCLUDES        = YES
 INCLUDE_PATH           =
 INCLUDE_FILE_PATTERNS  =
-PREDEFINED             = ENABLE_NETWORK ENABLE_AI WITH_ZLIB WITH_LZO WITH_PNG WITH_FONTCONFIG WITH_FREETYPE WITH_ICU UNICODE _UNICODE
+PREDEFINED             = ENABLE_NETWORK ENABLE_AI WITH_ZLIB WITH_LZO WITH_LZMA WITH_SDL WITH_PNG WITH_FONTCONFIG WITH_FREETYPE WITH_ICU UNICODE _UNICODE _GNU_SOURCE
 EXPAND_AS_DEFINED      =
 SKIP_FUNCTION_MACROS   = YES
 #---------------------------------------------------------------------------

src/road_cmd.cpp

@@ -1299,6 +1299,13 @@ static void DrawTile_Road(TileInfo *ti)
 	DrawBridgeMiddle(ti);
 }
 
+/**
+ * Draw the road depot sprite.
+ * @param x   The x offset to draw at.
+ * @param y   The y offset to draw at.
+ * @param dir The direction the depot must be facing.
+ * @param rt  The road type of the depot to draw.
+ */
 void DrawRoadDepotSprite(int x, int y, DiagDirection dir, RoadType rt)
 {
 	PaletteID palette = COMPANY_SPRITE_COLOUR(_local_company);

src/road_gui.cpp

@@ -833,6 +833,10 @@ static const WindowDesc _build_road_scen_desc(
 	_nested_build_road_scen_widgets, lengthof(_nested_build_road_scen_widgets)
 );
 
+/**
+ * Show the road building toolbar in the scenario editor.
+ * @return The just opened toolbar.
+ */
 Window *ShowBuildRoadScenToolbar()
 {
 	_cur_roadtype = ROADTYPE_ROAD;

src/road_map.h

@@ -260,6 +260,7 @@ enum DisallowedRoadDirections {
 	DRD_END
 };
 DECLARE_ENUM_AS_BIT_SET(DisallowedRoadDirections)
+/** Helper information for extract tool. */
 template <> struct EnumPropsT<DisallowedRoadDirections> : MakeEnumPropsT<DisallowedRoadDirections, byte, DRD_NONE, DRD_END, DRD_END, 2> {};
 
 /**
@@ -311,7 +312,7 @@ static inline Axis GetCrossingRailAxis(TileIndex t)
 
 /**
  * Get the road bits of a level crossing.
- * @param t The tile to query.
+ * @param tile The tile to query.
  * @return The present road bits.
  */
 static inline RoadBits GetCrossingRoadBits(TileIndex tile)
@@ -321,7 +322,7 @@ static inline RoadBits GetCrossingRoadBits(TileIndex tile)
 
 /**
  * Get the rail track of a level crossing.
- * @param t The tile to query.
+ * @param tile The tile to query.
  * @return The rail track.
  */
 static inline Track GetCrossingRailTrack(TileIndex tile)
@@ -331,7 +332,7 @@ static inline Track GetCrossingRailTrack(TileIndex tile)
 
 /**
  * Get the rail track bits of a level crossing.
- * @param t The tile to query.
+ * @param tile The tile to query.
  * @return The rail track bits.
  */
 static inline TrackBits GetCrossingRailBits(TileIndex tile)

src/roadstop.cpp

@@ -16,6 +16,7 @@
 #include "station_base.h"
 #include "vehicle_func.h"
 
+/** The pool of roadstops. */
 RoadStopPool _roadstop_pool("RoadStop");
 INSTANTIATE_POOL_METHODS(RoadStop)
 

src/saveload/cargopacket_sl.cpp

@@ -15,6 +15,9 @@
 
 #include "saveload.h"
 
+/**
+ * Savegame conversion for cargopackets.
+ */
 /* static */ void CargoPacket::AfterLoad()
 {
 	if (IsSavegameVersionBefore(44)) {
@@ -101,6 +104,9 @@ const SaveLoad *GetCargoPacketDesc()
 	return _cargopacket_desc;
 }
 
+/**
+ * Save the cargo packets.
+ */
 static void Save_CAPA()
 {
 	CargoPacket *cp;
@@ -111,6 +117,9 @@ static void Save_CAPA()
 	}
 }
 
+/**
+ * Load the cargo packets.
+ */
 static void Load_CAPA()
 {
 	int index;
@@ -121,6 +130,7 @@ static void Load_CAPA()
 	}
 }
 
+/** Chunk handlers related to cargo packets. */
 extern const ChunkHandler _cargopacket_chunk_handlers[] = {
 	{ 'CAPA', Save_CAPA, Load_CAPA, NULL, NULL, CH_ARRAY | CH_LAST},
 };

src/saveload/cheat_sl.cpp

@@ -14,6 +14,9 @@
 
 #include "saveload.h"
 
+/**
+ * Save the cheat values.
+ */
 static void Save_CHTS()
 {
 	/* Cannot use lengthof because _cheats is of type Cheats, not Cheat */
@@ -28,6 +31,9 @@ static void Save_CHTS()
 	}
 }
 
+/**
+ * Load the cheat values.
+ */
 static void Load_CHTS()
 {
 	Cheat *cht = (Cheat*)&_cheats;
@@ -39,6 +45,7 @@ static void Load_CHTS()
 	}
 }
 
+/** Chunk handlers related to cheats. */
 extern const ChunkHandler _cheat_chunk_handlers[] = {
 	{ 'CHTS', Save_CHTS, Load_CHTS, NULL, NULL, CH_RIFF | CH_LAST},
 };

src/saveload/signs_sl.cpp

@@ -14,6 +14,7 @@
 
 #include "saveload.h"
 
+/** Description of a sign within the savegame. */
 static const SaveLoad _sign_desc[] = {
   SLE_CONDVAR(Sign, name,  SLE_NAME,                   0, 83),
   SLE_CONDSTR(Sign, name,  SLE_STR, 0,                84, SL_MAX_VERSION),
@@ -56,6 +57,7 @@ static void Load_SIGN()
 	}
 }
 
+/** Chunk handlers related to signs. */
 extern const ChunkHandler _sign_chunk_handlers[] = {
 	{ 'SIGN', Save_SIGN, Load_SIGN, NULL, NULL, CH_ARRAY | CH_LAST},
 };

src/saveload/strings_sl.cpp

@@ -115,6 +115,9 @@ void InitializeOldNames()
 	_old_name_array = CallocT<char>(512 * 32); // 200 * 24 would be enough for TTO savegames
 }
 
+/**
+ * Load the NAME chunk.
+ */
 static void Load_NAME()
 {
 	int index;
@@ -124,6 +127,7 @@ static void Load_NAME()
 	}
 }
 
+/** Chunk handlers related to strings. */
 extern const ChunkHandler _name_chunk_handlers[] = {
 	{ 'NAME', NULL, Load_NAME, NULL, NULL, CH_ARRAY | CH_LAST},
 };

src/script/script_scanner.hpp

@@ -14,6 +14,7 @@
 
 #include "../fileio_type.h"
 
+/** Scanner to help finding scripts. */
 class ScriptScanner {
 public:
 	ScriptScanner();
@@ -43,8 +44,8 @@ private:
 	void ScanDir(const char *dirname, const char *info_file_name);
 
 protected:
-	class Squirrel *engine;
+	class Squirrel *engine; ///< The engine we're scanning with.
-	char main_script[1024];
+	char main_script[1024]; ///< The name of the current main script.
 };
 
 #endif /* SCRIPT_SCANNER_HPP */

src/script/squirrel_helper_type.hpp

@@ -12,9 +12,10 @@
 #ifndef SQUIRREL_HELPER_TYPE_HPP
 #define SQUIRREL_HELPER_TYPE_HPP
 
+/** Definition of a simple array. */
 struct Array {
-	int32 size;
+	int32 size;    ///< The size of the array.
-	int32 array[];
+	int32 array[]; ///< The data of the array.
 };
 
 #endif /* SQUIRREL_HELPER_TYPE_HPP */

src/sdl.cpp

@@ -16,6 +16,7 @@
 #include "sdl.h"
 #include <SDL.h>
 
+/** Number of users of the SDL library. */
 static int _sdl_usage;
 
 #ifdef DYNAMICALLY_LOADED_SDL
@@ -78,7 +79,10 @@ static const char *LoadSdlDLL()
 
 #endif /* DYNAMICALLY_LOADED_SDL */
 
-
+/**
+ * Open the SDL library.
+ * @param x The subsystem to load.
+ */
 const char *SdlOpen(uint32 x)
 {
 #ifdef DYNAMICALLY_LOADED_SDL
@@ -96,6 +100,10 @@ const char *SdlOpen(uint32 x)
 	return NULL;
 }
 
+/**
+ * Close the SDL library.
+ * @param x The subsystem to close.
+ */
 void SdlClose(uint32 x)
 {
 	if (x != 0) {

src/settingsgen/settingsgen.cpp

@@ -156,13 +156,18 @@ private:
 		return num_blocks > 0 && this->output_buffer[num_blocks - 1].HasRoom();
 	}
 
-	typedef SmallVector<OutputBuffer, 2> OutputBufferVector;
+	typedef SmallVector<OutputBuffer, 2> OutputBufferVector; ///< Vector type for output buffers.
 	OutputBufferVector output_buffer; ///< Vector of blocks containing the stored output.
 };
 
 
 /** Derived class for loading INI files without going through Fio stuff. */
 struct SettingsIniFile : IniLoadFile {
+	/**
+	 * Construct a new ini loader.
+	 * @param list_group_names A \c NULL terminated list with group names that should be loaded as lists instead of variables. @see IGT_LIST
+	 * @param seq_group_names  A \c NULL terminated list with group names that should be loaded as lists of names. @see IGT_SEQUENCE
+	 */
 	SettingsIniFile(const char * const *list_group_names = NULL, const char * const *seq_group_names = NULL) :
 			IniLoadFile(list_group_names, seq_group_names)
 	{

src/ship.h

@@ -20,7 +20,7 @@ void GetShipSpriteSize(EngineID engine, uint &width, uint &height);
  * All ships have this type.
  */
 struct Ship: public SpecializedVehicle<Ship, VEH_SHIP> {
-	TrackBitsByte state;
+	TrackBitsByte state; ///< The "track" the ship is following.
 
 	/** We don't want GCC to zero our struct! It already is zeroed and has an index! */
 	Ship() : SpecializedVehicleBase() {}
@@ -45,6 +45,10 @@ struct Ship: public SpecializedVehicle<Ship, VEH_SHIP> {
 	void UpdateCache();
 };
 
+/**
+ * Iterate over all ships.
+ * @param var The variable used for iteration.
+ */
 #define FOR_ALL_SHIPS(var) FOR_ALL_VEHICLES_OF_TYPE(Ship, var)
 
 #endif /* SHIP_H */

src/ship_cmd.cpp

@@ -150,6 +150,9 @@ static void CheckIfShipNeedsService(Vehicle *v)
 	SetWindowWidgetDirty(WC_VEHICLE_VIEW, v->index, VVW_WIDGET_START_STOP_VEH);
 }
 
+/**
+ * Update the caches of this ship.
+ */
 void Ship::UpdateCache()
 {
 	this->vcache.cached_max_speed = GetVehicleProperty(this, PROP_SHIP_SPEED, ShipVehInfo(this->engine_type)->max_speed);

src/signal_type.h

@@ -34,6 +34,7 @@ enum SignalType {
 	SIGTYPE_LAST       = SIGTYPE_PBS_ONEWAY,
 	SIGTYPE_LAST_NOPBS = SIGTYPE_COMBO
 };
+/** Helper information for extract tool. */
 template <> struct EnumPropsT<SignalType> : MakeEnumPropsT<SignalType, byte, SIGTYPE_NORMAL, SIGTYPE_END, SIGTYPE_END, 3> {};
 
 

src/signs.cpp

@@ -18,7 +18,7 @@
 
 #include "table/strings.h"
 
-/* Initialize the sign-pool */
+/** Initialize the sign-pool */
 SignPool _sign_pool("Sign");
 INSTANTIATE_POOL_METHODS(Sign)
 

src/signs_cmd.cpp

@@ -21,6 +21,7 @@
 
 #include "table/strings.h"
 
+/** The last built sign. */
 SignID _new_sign_id;
 
 /**

src/signs_gui.cpp

@@ -638,6 +638,10 @@ static const WindowDesc _query_sign_edit_desc(
 	_nested_query_sign_edit_widgets, lengthof(_nested_query_sign_edit_widgets)
 );
 
+/**
+ * Handle clicking on a sign.
+ * @param si The sign that was clicked on.
+ */
 void HandleClickOnSign(const Sign *si)
 {
 	if (_ctrl_pressed && si->owner == _local_company) {
@@ -647,6 +651,10 @@ void HandleClickOnSign(const Sign *si)
 	ShowRenameSignWindow(si);
 }
 
+/**
+ * Show the window to change the text of a sign.
+ * @param si The sign to show the window for.
+ */
 void ShowRenameSignWindow(const Sign *si)
 {
 	/* Delete all other edit windows */
@@ -655,6 +663,10 @@ void ShowRenameSignWindow(const Sign *si)
 	new SignWindow(&_query_sign_edit_desc, si);
 }
 
+/**
+ * Close the sign window associated with the given sign.
+ * @param sign The sign to close the window for.
+ */
 void DeleteRenameSignWindow(SignID sign)
 {
 	SignWindow *w = dynamic_cast<SignWindow *>(FindWindowById(WC_QUERY_STRING, 0));

src/signs_type.h

@@ -12,10 +12,11 @@
 #ifndef SIGNS_TYPE_H
 #define SIGNS_TYPE_H
 
+/** The type of the IDs of signs. */
 typedef uint16 SignID;
 struct Sign;
 
-static const SignID INVALID_SIGN = 0xFFFF;
+static const SignID INVALID_SIGN = 0xFFFF; ///< Sentinel for an invalid sign.
 
 static const uint MAX_LENGTH_SIGN_NAME_CHARS = 32; ///< The maximum length of a sign name in characters including '\0'
 

src/slope_type.h

@@ -79,6 +79,10 @@ enum Slope {
 };
 DECLARE_ENUM_AS_BIT_SET(Slope)
 
+/**
+ * Helper for creating a bitset of slopes.
+ * @param x The slope to convert into a bitset.
+ */
 #define M(x) (1 << (x))
 /** Constant bitset with safe slopes for building a level crossing. */
 static const uint32 VALID_LEVEL_CROSSING_SLOPES = M(SLOPE_SEN) | M(SLOPE_ENW) | M(SLOPE_NWS) | M(SLOPE_NS) | M(SLOPE_WSE) | M(SLOPE_EW) | M(SLOPE_FLAT);

src/smallmap_gui.cpp

@@ -292,6 +292,9 @@ static const SmallMapColourScheme _heightmap_schemes[] = {
 	{_violet_map_heights,     MKCOLOUR(0x82828282)}, ///< Violet colour scheme.
 };
 
+/**
+ * (Re)build the colour tables for the legends.
+ */
 void BuildLandLegend()
 {
 	for (LegendAndColour *lc = _legend_land_contours; lc->legend == STR_TINY_BLACK_HEIGHT; lc++) {
@@ -1709,6 +1712,9 @@ static const WindowDesc _smallmap_desc(
 	_nested_smallmap_widgets, lengthof(_nested_smallmap_widgets)
 );
 
+/**
+ * Show the smallmap window.
+ */
 void ShowSmallMap()
 {
 	AllocateWindowDescFront<SmallMapWindow>(&_smallmap_desc, 0);

src/sound/null_s.cpp

@@ -12,4 +12,5 @@
 #include "../stdafx.h"
 #include "null_s.h"
 
+/** The factory for the null sound driver. */
 static FSoundDriver_Null iFSoundDriver_Null;

src/sound/sdl_s.cpp

@@ -18,8 +18,15 @@
 #include "sdl_s.h"
 #include <SDL.h>
 
+/** Factory for the SDL sound driver. */
 static FSoundDriver_SDL iFSoundDriver_SDL;
 
+/**
+ * Callback that fills the sound buffer.
+ * @param userdata Ignored.
+ * @param stream   The stream to put data into.
+ * @param len      The length of the stream in bytes.
+ */
 static void CDECL fill_sound_buffer(void *userdata, Uint8 *stream, int len)
 {
 	MxMixSamples(stream, len / 4);

src/spriteloader/spriteloader.hpp

@@ -15,8 +15,10 @@
 #include "../core/alloc_type.hpp"
 #include "../gfx_type.h"
 
+/** Interface for the loader of our sprites. */
 class SpriteLoader {
 public:
+	/** Definition of a common pixel in OpenTTD's realm. */
 	struct CommonPixel {
 		uint8 r;  ///< Red-channel
 		uint8 g;  ///< Green-channel

src/station.cpp

@@ -28,6 +28,7 @@
 
 #include "table/strings.h"
 
+/** The pool of stations. */
 StationPool _station_pool("Station");
 INSTANTIATE_POOL_METHODS(Station)
 
@@ -275,8 +276,8 @@ Rect Station::GetCatchmentRect() const
 
 /** Rect and pointer to IndustryVector */
 struct RectAndIndustryVector {
-	Rect rect;
+	Rect rect;                       ///< The rectangle to search the industries in.
-	IndustryVector *industries_near;
+	IndustryVector *industries_near; ///< The nearby industries.
 };
 
 /**

src/station_map.h

@@ -33,8 +33,8 @@ static inline StationID GetStationIndex(TileIndex t)
 }
 
 
-static const int GFX_DOCK_BASE_WATER_PART          =  4;
+static const int GFX_DOCK_BASE_WATER_PART          =  4; ///< The offset for the water parts.
-static const int GFX_TRUCK_BUS_DRIVETHROUGH_OFFSET =  4;
+static const int GFX_TRUCK_BUS_DRIVETHROUGH_OFFSET =  4; ///< The offset for the drive through parts.
 
 /**
  * Get the station type of this tile
@@ -476,6 +476,7 @@ static inline bool IsCustomStationSpecIndex(TileIndex t)
 /**
  * Set the custom station spec for this tile.
  * @param t Tile to set the stationspec of.
+ * @param specindex The new spec.
  * @pre HasStationTileRail(t)
  */
 static inline void SetCustomStationSpecIndex(TileIndex t, byte specindex)
@@ -498,7 +499,8 @@ static inline uint GetCustomStationSpecIndex(TileIndex t)
 
 /**
  * Set the random bits for a station tile.
- * @param t Tile to set random bits for
+ * @param t Tile to set random bits for.
+ * @param random_bits The random bits.
  * @pre IsTileType(t, MP_STATION)
  */
 static inline void SetStationTileRandomBits(TileIndex t, byte random_bits)
@@ -526,6 +528,7 @@ static inline byte GetStationTileRandomBits(TileIndex t)
  * @param sid the station to which this tile belongs
  * @param st the type this station tile
  * @param section the StationGfx to be used for this tile
+ * @param wc The water class of the station
  */
 static inline void MakeStation(TileIndex t, Owner o, StationID sid, StationType st, byte section, WaterClass wc = WATER_CLASS_INVALID)
 {
@@ -599,7 +602,7 @@ static inline void MakeRoadStop(TileIndex t, Owner o, StationID sid, RoadStopTyp
  * @param sid the station to which this tile belongs
  * @param rst the type of roadstop to make this tile
  * @param rt the roadtypes on this tile
- * @param d the direction of the roadstop
+ * @param a the direction of the roadstop
  */
 static inline void MakeDriveThroughRoadStop(TileIndex t, Owner station, Owner road, Owner tram, StationID sid, RoadStopType rst, RoadTypes rt, Axis a)
 {

src/statusbar_gui.cpp

@@ -257,6 +257,9 @@ bool IsNewsTickerShown()
 
 int16 *_preferred_statusbar_size = &_main_status_desc.default_width; ///< Pointer to the default size for the status toolbar.
 
+/**
+ * Show our status bar.
+ */
 void ShowStatusBar()
 {
 	new StatusBarWindow(&_main_status_desc);

src/statusbar_gui.h

@@ -12,6 +12,7 @@
 #ifndef STATUSBAR_GUI_H
 #define STATUSBAR_GUI_H
 
+/** What of the statusbar must be invalidated? */
 enum StatusBarInvalidate {
 	SBI_SAVELOAD_START,  ///< started saving
 	SBI_SAVELOAD_FINISH, ///< finished saving

src/string.cpp

@@ -160,7 +160,11 @@ char *strecpy(char *dst, const char *src, const char *last)
 	return dst;
 }
 
-
+/**
+ * Format, "printf", into a newly allocated string.
+ * @param str The formatting string.
+ * @return The formatted string. You must free this!
+ */
 char *CDECL str_fmt(const char *str, ...)
 {
 	char buf[4096];

src/string_type.h

@@ -29,6 +29,7 @@ enum CharSetFilter {
 	CS_HEXADECIMAL,       ///< Only hexadecimal characters
 };
 
+/** Type for wide characters, i.e. non-UTF8 encoded unicode characters. */
 typedef uint32 WChar;
 
 /* The following are directional formatting codes used to get the LTR and RTL strings right:

src/subsidy_type.h

@@ -20,6 +20,7 @@ enum PartOfSubsidy {
 	POS_SRC = 1 << 0, ///< bit 0 set -> town/industry is source of subsidised path
 	POS_DST = 1 << 1, ///< bit 1 set -> town/industry is destination of subsidised path
 };
+/** Helper to store the PartOfSubsidy data in a single byte. */
 typedef SimpleTinyEnumT<PartOfSubsidy, byte> PartOfSubsidyByte;
 
 DECLARE_ENUM_AS_BIT_SET(PartOfSubsidy)

src/waypoint_gui.cpp

@@ -54,6 +54,11 @@ private:
 	}
 
 public:
+	/**
+	 * Construct the window.
+	 * @param desc The description of the window.
+	 * @param window_number The window number, in this case the waypoint's ID.
+	 */
 	WaypointWindow(const WindowDesc *desc, WindowNumber window_number) : Window()
 	{
 		this->wp = Waypoint::Get(window_number);