diff -r b4bed389d825 src/cargo_type.h --- a/src/cargo_type.h Thu Oct 16 13:02:15 2008 +0000 +++ b/src/cargo_type.h Fri Oct 17 18:03:21 2008 +0200 @@ -7,7 +7,8 @@ typedef byte CargoID; -enum { +/** Available types of cargo */ +enum CargoTypes { // Temperate CT_PASSENGERS = 0, CT_COAL = 1, @@ -54,6 +55,7 @@ CT_INVALID = 0xFF }; +/** Array for storing amounts of accepted cargo */ typedef uint AcceptedCargo[NUM_CARGO]; -#endif /* OPENTTD_H */ +#endif /* CARGO_TYPE_H */ diff -r b4bed389d825 src/landscape.cpp --- a/src/landscape.cpp Thu Oct 16 13:02:15 2008 +0000 +++ b/src/landscape.cpp Fri Oct 17 18:03:21 2008 +0200 @@ -44,18 +44,20 @@ _tile_type_tunnelbridge_procs, _tile_type_unmovable_procs; +/** Tile callback functions for each type of tile. + * @see TileType */ const TileTypeProcs * const _tile_type_procs[16] = { - &_tile_type_clear_procs, - &_tile_type_rail_procs, - &_tile_type_road_procs, - &_tile_type_town_procs, - &_tile_type_trees_procs, - &_tile_type_station_procs, - &_tile_type_water_procs, - &_tile_type_dummy_procs, - &_tile_type_industry_procs, - &_tile_type_tunnelbridge_procs, - &_tile_type_unmovable_procs, + &_tile_type_clear_procs, ///< Callback functions for MP_CLEAR tiles + &_tile_type_rail_procs, ///< Callback functions for MP_RAILWAY tiles + &_tile_type_road_procs, ///< Callback functions for MP_ROAD tiles + &_tile_type_town_procs, ///< Callback functions for MP_HOUSE tiles + &_tile_type_trees_procs, ///< Callback functions for MP_TREES tiles + &_tile_type_station_procs, ///< Callback functions for MP_STATION tiles + &_tile_type_water_procs, ///< Callback functions for MP_WATER tiles + &_tile_type_dummy_procs, ///< Callback functions for MP_VOID tiles + &_tile_type_industry_procs, ///< Callback functions for MP_INDUSTRY tiles + &_tile_type_tunnelbridge_procs, ///< Callback functions for MP_TUNNELBRIDGE tiles + &_tile_type_unmovable_procs, ///< Callback functions for MP_UNMOVABLE tiles }; /* landscape slope => sprite */ @@ -64,6 +66,12 @@ 0, 0, 0, 0, 0, 0, 0, 16, 0, 0, 0, 17, 0, 15, 18, 0, }; +/** + * Description of the snow line throughout the year. + * + * If it is \c NULL, a static snowline height is used, as set by \c _settings_game.game_creation.snow_line. + * Otherwise it points to a table loaded from a newGRF file, that describes the variable snowline + * @see GetSnowLine() GameCreationSettings */ SnowLine *_snow_line = NULL; /** diff -r b4bed389d825 src/landscape.h --- a/src/landscape.h Thu Oct 16 13:02:15 2008 +0000 +++ b/src/landscape.h Fri Oct 17 18:03:21 2008 +0200 @@ -15,9 +15,10 @@ SNOW_LINE_DAYS = 32, }; +/** Structure describing the height of the snow line each day of the year */ struct SnowLine { - byte table[SNOW_LINE_MONTHS][SNOW_LINE_DAYS]; - byte highest_value; + byte table[SNOW_LINE_MONTHS][SNOW_LINE_DAYS]; ///< Height of the snow line each day of the year + byte highest_value; ///< Highest snow line of the year }; bool IsSnowLineSet(void); diff -r b4bed389d825 src/rail_cmd.cpp --- a/src/rail_cmd.cpp Thu Oct 16 13:02:15 2008 +0000 +++ b/src/rail_cmd.cpp Fri Oct 17 18:03:21 2008 +0200 @@ -2463,7 +2463,8 @@ return 0; // make compilers happy } - +/** Tile callback routine when vehicle enters tile + * @see vehicle_enter_tile_proc */ static VehicleEnterTileStatus VehicleEnter_Track(Vehicle *v, TileIndex tile, int x, int y) { byte fract_coord; diff -r b4bed389d825 src/tile_cmd.h --- a/src/tile_cmd.h Thu Oct 16 13:02:15 2008 +0000 +++ b/src/tile_cmd.h Fri Oct 17 18:03:21 2008 +0200 @@ -47,26 +47,44 @@ uint z; }; +/** Tile description for the 'land area information' tool */ struct TileDesc { - StringID str; - Owner owner[4]; - StringID owner_type[4]; - Date build_date; - StringID station_class; - StringID station_name; - const char *grf; - uint64 dparam[2]; + StringID str; ///< Description of the tile + Owner owner[4]; ///< Name of the owner(s) + StringID owner_type[4]; ///< Type of each owner + Date build_date; ///< Date of construction of tile contents + StringID station_class; ///< Class of station + StringID station_name; ///< Type of station within the class + const char *grf; ///< newGRF used for the tile contents + uint64 dparam[2]; ///< Parameters of the \a str string }; +/** + * Tile callback function signature for drawing a tile and its contents to the screen + * @param tile Tile to draw + */ typedef void DrawTileProc(TileInfo *ti); typedef uint GetSlopeZProc(TileIndex tile, uint x, uint y); typedef CommandCost ClearTileProc(TileIndex tile, byte flags); + +/** + * Tile callback function signature for obtaining accepted carog of a tile + * @param tile Tile queried for its accepted cargo + * @param res Storage destination of the cargo accepted + */ typedef void GetAcceptedCargoProc(TileIndex tile, AcceptedCargo res); + +/** + * Tile callback function signature for obtaining a tile description + * @param tile Tile being queried + * @param td Storage pointer for returned tile description + */ typedef void GetTileDescProc(TileIndex tile, TileDesc *td); /** - * GetTileTrackStatusProcs return a value that contains the possible tracks + * Tile callback function signature for getting the possible tracks * that can be taken on a given tile by a given transport. + * * The return value contains the existing trackdirs and signal states. * * see track_func.h for usage of TrackStatus. @@ -77,6 +95,12 @@ * @return the track status information */ typedef TrackStatus GetTileTrackStatusProc(TileIndex tile, TransportType mode, uint sub_mode, DiagDirection side); + +/** + * Tile callback function signature for obtaining the produced cargo of a tile. + * @param tile Tile being queried + * @param b Destination array of produced cargo + */ typedef void GetProducedCargoProc(TileIndex tile, CargoID *b); typedef void ClickTileProc(TileIndex tile); typedef void AnimateTileProc(TileIndex tile); @@ -88,9 +112,11 @@ typedef Foundation GetFoundationProc(TileIndex tile, Slope tileh); /** - * Called when a tile is affected by a terraforming operation. - * The function has to check if terraforming of the tile is allowed and return extra terraform-cost that depend on the tiletype. - * With DC_EXEC in flags it has to perform tiletype-specific actions (like clearing land etc., but not the terraforming itself). + * Tile callback function signature of the terraforming callback. + * + * The function is called when a tile is affected by a terraforming operation. + * It has to check if terraforming of the tile is allowed and return extra terraform-cost that depend on the tiletype. + * With DC_EXEC in \a flags it has to perform tiletype-specific actions (like clearing land etc., but not the terraforming itself). * * @note The terraforming has not yet taken place. So GetTileZ() and GetTileSlope() refer to the landscape before the terraforming operation. * @@ -106,20 +132,20 @@ * Set of callback functions for performing tile operations of a given tile type. * @see TileType */ struct TileTypeProcs { - DrawTileProc *draw_tile_proc; + DrawTileProc *draw_tile_proc; ///< Called to render the tile and its contents to the screen GetSlopeZProc *get_slope_z_proc; ClearTileProc *clear_tile_proc; - GetAcceptedCargoProc *get_accepted_cargo_proc; - GetTileDescProc *get_tile_desc_proc; - GetTileTrackStatusProc *get_tile_track_status_proc; - ClickTileProc *click_tile_proc; + GetAcceptedCargoProc *get_accepted_cargo_proc; ///< Return accepted cargo of the tile + GetTileDescProc *get_tile_desc_proc; ///< Get a description of a tile (for the 'land area information' tool) + GetTileTrackStatusProc *get_tile_track_status_proc; ///< Get available tracks and status of a tile + ClickTileProc *click_tile_proc; ///< Called when tile is clicked AnimateTileProc *animate_tile_proc; TileLoopProc *tile_loop_proc; ChangeTileOwnerProc *change_tile_owner_proc; - GetProducedCargoProc *get_produced_cargo_proc; - VehicleEnterTileProc *vehicle_enter_tile_proc; + GetProducedCargoProc *get_produced_cargo_proc; ///< Return produced cargo of the tile + VehicleEnterTileProc *vehicle_enter_tile_proc; ///< Called when a vehicle enters a tile GetFoundationProc *get_foundation_proc; - TerraformTileProc *terraform_tile_proc; + TerraformTileProc *terraform_tile_proc; ///< Called when a terraforming operation is about to take place }; extern const TileTypeProcs * const _tile_type_procs[16]; diff -r b4bed389d825 src/town_cmd.cpp --- a/src/town_cmd.cpp Thu Oct 16 13:02:15 2008 +0000 +++ b/src/town_cmd.cpp Fri Oct 17 18:03:21 2008 +0200 @@ -224,6 +224,7 @@ return GetTileMaxZ(tile); } +/** Tile callback routine */ static Foundation GetFoundation_Town(TileIndex tile, Slope tileh) { return FlatteningFoundation(tileh); @@ -399,7 +400,7 @@ MarkTileDirtyByTile(tile); } -/** Make the house advances in its construction stages until completion +/** Make the house advance in its construction stages until completion * @param tile TileIndex of house */ static void MakeTownHouseBigger(TileIndex tile) @@ -412,6 +413,8 @@ } /** + * Tile callback function. + * * Periodic tic handler for houses and town * @param tile been asked to do its stuff */ @@ -507,7 +510,7 @@ } /** - * Unused handler + * Dummy tile callback function for handling tile clicks in towns * @param tile unused */ static void ClickTile_Town(TileIndex tile) @@ -2002,7 +2005,12 @@ return false; } - +/** + * Update data structures when a house is removed + * @param tile Tile of the house + * @param t Town owning the house + * @param house House type + */ static void DoClearTownHouseHelper(TileIndex tile, Town *t, HouseID house) { assert(IsTileType(tile, MP_HOUSE)); @@ -2601,6 +2609,7 @@ return DoCommand(tile, 0, 0, flags, CMD_LANDSCAPE_CLEAR); } +/** Tile callback functions for a town */ extern const TileTypeProcs _tile_type_town_procs = { DrawTile_Town, /* draw_tile_proc */ GetSlopeZ_Town, /* get_slope_z_proc */ diff -r b4bed389d825 src/transport_type.h --- a/src/transport_type.h Thu Oct 16 13:02:15 2008 +0000 +++ b/src/transport_type.h Fri Oct 17 18:03:21 2008 +0200 @@ -7,6 +7,7 @@ typedef uint16 UnitID; +/** Available types of transport */ enum TransportType { /* These constants are for now linked to the representation of bridges * and tunnels, so they can be used by GetTileTrackStatus_TunnelBridge. @@ -15,10 +16,10 @@ * the values for road and rail. */ TRANSPORT_BEGIN = 0, - TRANSPORT_RAIL = TRANSPORT_BEGIN, - TRANSPORT_ROAD, - TRANSPORT_WATER, - TRANSPORT_AIR, + TRANSPORT_RAIL = TRANSPORT_BEGIN, ///< Transport by train + TRANSPORT_ROAD, ///< Transport by road vehicle + TRANSPORT_WATER, ///< Transport over water + TRANSPORT_AIR, ///< Transport through air TRANSPORT_END, INVALID_TRANSPORT = 0xff, }; diff -r b4bed389d825 src/vehicle.cpp --- a/src/vehicle.cpp Thu Oct 16 13:02:15 2008 +0000 +++ b/src/vehicle.cpp Fri Oct 17 18:03:21 2008 +0200 @@ -1779,7 +1779,10 @@ MarkAllViewportsDirty(v->left_coord, v->top_coord, v->right_coord + 1, v->bottom_coord + 1); } -/* returns true if staying in the same tile */ +/** + * Get position information of a vehicle when moving one pixel in the direction it is facing + * @param v Vehicle to move + * @return Position information after the move */ GetNewVehiclePosResult GetNewVehiclePos(const Vehicle *v) { static const int8 _delta_coord[16] = { @@ -1870,7 +1873,12 @@ } /** - * Returns some meta-data over the to be entered tile. + * Call the tile callback function for a vehicle entering a tile + * @param v Vehicle entering the tile + * @param tile Tile entered + * @param x X position + * @param y Y position + * @return Some meta-data over the to be entered tile. * @see VehicleEnterTileStatus to see what the bits in the return value mean. */ uint32 VehicleEnterTile(Vehicle *v, TileIndex tile, int x, int y) diff -r b4bed389d825 src/vehicle_func.h --- a/src/vehicle_func.h Thu Oct 16 13:02:15 2008 +0000 +++ b/src/vehicle_func.h Fri Oct 17 18:03:21 2008 +0200 @@ -75,14 +75,13 @@ void CcCloneVehicle(bool success, TileIndex tile, uint32 p1, uint32 p2); - +/** Position information of a vehicle after it moved */ struct GetNewVehiclePosResult { - int x, y; - TileIndex old_tile; - TileIndex new_tile; + int x, y; ///< x and y position of the vehicle after moving + TileIndex old_tile; ///< Current tile of the vehicle + TileIndex new_tile; ///< Tile of the vehicle after moving }; -/* returns true if staying in the same tile */ GetNewVehiclePosResult GetNewVehiclePos(const Vehicle *v); Direction GetDirectionTowards(const Vehicle *v, int x, int y);