mirror
/
OpenTTD
mirror of https://github.com/OpenTTD/OpenTTD
1
0
Fork 0
Code Issues

(svn r20283) -Codechange: Unify start of doygen comments.

release/1.1
frosch 2010-08-01 19:22:34 +00:00
parent 4871baf44d
commit ed4f806f1d
162 changed files with 1304 additions and 652 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
src/ai/api/ai_changelog.hpp
View File

@ -7,7 +7,8 @@
* 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 ai_changelog.hpp Lists all changes / additions to the API.
/**
* @file ai_changelog.hpp Lists all changes / additions to the API.
*
* Only new / renamed / deleted api functions will be listed here. A list of
* bug fixes can be found in the normal changelog. Note that removed API

3
src/ai/api/ai_types.hpp
View File

@ -7,7 +7,8 @@
* 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 ai_types.hpp Defines all the types of the game, like IDs of various objects.
/**
* @file ai_types.hpp Defines all the types of the game, like IDs of various objects.
*
* IDs are used to identify certain objects. They are only unique within the object type, so for example a vehicle may have VehicleID 2009,
* while a station has StationID 2009 at the same time. Also IDs are assigned arbitrary, you cannot assume them to be consecutive.

9
src/aircraft.h
View File

@ -26,12 +26,14 @@ enum AircraftSubType {
};
/** Handle Aircraft specific tasks when a an Aircraft enters a hangar
/**
* Handle Aircraft specific tasks when a an Aircraft enters a hangar
* @param *v Vehicle that enters the hangar
*/
void HandleAircraftEnterHangar(Aircraft *v);
/** Get the size of the sprite of an aircraft sprite heading west (used for lists)
/**
* Get the size of the sprite of an aircraft sprite heading west (used for lists)
* @param engine The engine to get the sprite from
* @param width The width of the sprite
* @param height The height of the sprite
@ -44,7 +46,8 @@ void GetAircraftSpriteSize(EngineID engine, uint &width, uint &height);
*/
void UpdateAirplanesOnNewStation(const Station *st);
/** Update cached values of an aircraft.
/**
* Update cached values of an aircraft.
* Currently caches callback 36 max speed.
* @param v Vehicle
*/

33
src/aircraft_cmd.cpp
View File

@ -7,7 +7,8 @@
* 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 aircraft_cmd.cpp
/**
* @file aircraft_cmd.cpp
* This file deals with aircraft and airport movements functionalities */
#include "stdafx.h"
@ -70,7 +71,8 @@ void Aircraft::UpdateDeltaXY(Direction direction)
}
/** this maps the terminal to its corresponding state and block flag
/**
* this maps the terminal to its corresponding state and block flag
* currently set for 10 terms, 4 helipads */
static const byte _airport_terminal_state[] = {2, 3, 4, 5, 6, 7, 19, 20, 0, 0, 8, 9, 21, 22};
static const byte _airport_terminal_flag[] = {0, 1, 2, 3, 4, 5, 22, 23, 0, 0, 6, 7, 24, 25};
@ -100,7 +102,8 @@ enum HelicopterRotorStates {
HRS_ROTOR_MOVING_3,
};
/** Find the nearest hangar to v
/**
* Find the nearest hangar to v
* INVALID_STATION is returned, if the company does not have any suitable
* airports (like helipads only)
* @param v vehicle looking for a hangar
@ -137,7 +140,8 @@ static StationID FindNearestHangar(const Aircraft *v)
}
#if 0
/** Check if given vehicle has a goto hangar in his orders
/**
* Check if given vehicle has a goto hangar in his orders
* @param v vehicle to inquiry
* @return true if vehicle v has an airport in the schedule, that has a hangar */
static bool HaveHangarInOrderList(Aircraft *v)
@ -213,7 +217,8 @@ void DrawAircraftEngine(int left, int right, int preferred_x, int y, EngineID en
}
}
/** Get the size of the sprite of an aircraft sprite heading west (used for lists)
/**
* Get the size of the sprite of an aircraft sprite heading west (used for lists)
* @param engine The engine to get the sprite from
* @param width The width of the sprite
* @param height The height of the sprite
@ -226,7 +231,8 @@ void GetAircraftSpriteSize(EngineID engine, uint &width, uint &height)
height = spr->height;
}
/** Build an aircraft.
/**
* Build an aircraft.
* @param tile tile of depot where aircraft is built
* @param flags for command
* @param p1 aircraft type being built (engine)
@ -383,7 +389,8 @@ CommandCost CmdBuildAircraft(TileIndex tile, DoCommandFlag flags, uint32 p1, uin
}
/** Sell an aircraft.
/**
* Sell an aircraft.
* @param tile unused
* @param flags for command type
* @param p1 vehicle ID to be sold
@ -431,7 +438,8 @@ bool Aircraft::FindClosestDepot(TileIndex *location, DestinationID *destination,
return true;
}
/** Send an aircraft to the hangar.
/**
* Send an aircraft to the hangar.
* @param tile unused
* @param flags for command type
* @param p1 vehicle ID to send to the hangar
@ -456,7 +464,8 @@ CommandCost CmdSendAircraftToHangar(TileIndex tile, DoCommandFlag flags, uint32
}
/** Refits an aircraft to the specified cargo type.
/**
* Refits an aircraft to the specified cargo type.
* @param tile unused
* @param flags for command type
* @param p1 vehicle ID of the aircraft to refit
@ -634,7 +643,8 @@ void SetAircraftPosition(Aircraft *v, int x, int y, int z)
}
}
/** Handle Aircraft specific tasks when a an Aircraft enters a hangar
/**
* Handle Aircraft specific tasks when a an Aircraft enters a hangar
* @param *v Vehicle that enters the hangar
*/
void HandleAircraftEnterHangar(Aircraft *v)
@ -1952,7 +1962,8 @@ bool Aircraft::Tick()
}
/** Returns aircraft's target station if v->target_airport
/**
* Returns aircraft's target station if v->target_airport
* is a valid station with airport.
* @param v vehicle to get target airport for
* @return pointer to target station, NULL if invalid

6
src/airport.cpp
View File

@ -227,7 +227,8 @@ AirportFTAClass::~AirportFTAClass()
free(layout);
}
/** Get the number of elements of a source Airport state automata
/**
* Get the number of elements of a source Airport state automata
* Since it is actually just a big array of AirportFTA types, we only
* know one element from the other by differing 'position' identifiers */
static uint16 AirportGetNofElements(const AirportFTAbuildup *apFA)
@ -245,7 +246,8 @@ static uint16 AirportGetNofElements(const AirportFTAbuildup *apFA)
return nofelements;
}
/** We calculate the terminal/helipod count based on the data passed to us
/**
* We calculate the terminal/helipod count based on the data passed to us
* This data (terminals) contains an index as a first element as to how many
* groups there are, and then the number of terminals for each group */
static byte AirportGetTerminalCount(const byte *terminals, byte *groups)

30
src/autoreplace_cmd.cpp
View File

@ -30,7 +30,8 @@ extern void ChangeVehicleViewports(VehicleID from_index, VehicleID to_index);
extern void ChangeVehicleNews(VehicleID from_index, VehicleID to_index);
extern void ChangeVehicleViewWindow(VehicleID from_index, VehicleID to_index);
/** Figure out if two engines got at least one type of cargo in common (refitting if needed)
/**
* Figure out if two engines got at least one type of cargo in common (refitting if needed)
* @param engine_a one of the EngineIDs
* @param engine_b the other EngineID
* @param type the type of the engines
@ -91,7 +92,8 @@ bool CheckAutoreplaceValidity(EngineID from, EngineID to, CompanyID company)
return EnginesHaveCargoInCommon(from, to);
}
/** Transfer cargo from a single (articulated )old vehicle to the new vehicle chain
/**
* Transfer cargo from a single (articulated )old vehicle to the new vehicle chain
* @param old_veh Old vehicle that will be sold
* @param new_head Head of the completely constructed new vehicle chain
* @param part_of_chain The vehicle is part of a train
@ -210,7 +212,8 @@ static CargoID GetNewCargoTypeForReplace(Vehicle *v, EngineID engine_type, bool
}
}
/** Get the EngineID of the replacement for a vehicle
/**
* Get the EngineID of the replacement for a vehicle
* @param v The vehicle to find a replacement for
* @param c The vehicle's owner (it's faster to forward the pointer than refinding it)
* @return the EngineID of the replacement. INVALID_ENGINE if no buildable replacement is found
@ -238,7 +241,8 @@ static EngineID GetNewEngineType(const Vehicle *v, const Company *c)
return INVALID_ENGINE;
}
/** Builds and refits a replacement vehicle
/**
* Builds and refits a replacement vehicle
* Important: The old vehicle is still in the original vehicle chain (used for determining the cargo when the old vehicle did not carry anything, but the new one does)
* @param old_veh A single (articulated/multiheaded) vehicle that shall be replaced.
* @param new_vehicle Returns the newly build and refittet vehicle
@ -284,7 +288,8 @@ static CommandCost BuildReplacementVehicle(Vehicle *old_veh, Vehicle **new_vehic
return cost;
}
/** Issue a start/stop command
/**
* Issue a start/stop command
* @param v a vehicle
* @param evaluate_callback shall the start/stop callback be evaluated?
* @return success or error
@ -294,7 +299,8 @@ static inline CommandCost StartStopVehicle(const Vehicle *v, bool evaluate_callb
return DoCommand(0, v->index, evaluate_callback ? 1 : 0, DC_EXEC | DC_AUTOREPLACE, CMD_START_STOP_VEHICLE);
}
/** Issue a train vehicle move command
/**
* Issue a train vehicle move command
* @param v The vehicle to move
* @param after The vehicle to insert 'v' after, or NULL to start new chain
* @param flags the command flags to use
@ -306,7 +312,8 @@ static inline CommandCost MoveVehicle(const Vehicle *v, const Vehicle *after, Do
return DoCommand(0, v->index | (after != NULL ? after->index : INVALID_VEHICLE) << 16, whole_chain ? 1 : 0, flags, CMD_MOVE_RAIL_VEHICLE);
}
/** Copy head specific things to the new vehicle chain after it was successfully constructed
/**
* Copy head specific things to the new vehicle chain after it was successfully constructed
* @param old_head The old front vehicle (no wagons attached anymore)
* @param new_head The new head of the completely replaced vehicle chain
* @param flags the command flags to use
@ -350,7 +357,8 @@ static CommandCost CopyHeadSpecificThings(Vehicle *old_head, Vehicle *new_head,
return cost;
}
/** Replace a single unit in a free wagon chain
/**
* Replace a single unit in a free wagon chain
* @param single_unit vehicle to let autoreplace/renew operator on
* @param flags command flags
* @param nothing_to_do is set to 'false' when something was done (only valid when not failed)
@ -398,7 +406,8 @@ static CommandCost ReplaceFreeUnit(Vehicle **single_unit, DoCommandFlag flags, b
return cost;
}
/** Replace a whole vehicle chain
/**
* Replace a whole vehicle chain
* @param chain vehicle chain to let autoreplace/renew operator on
* @param flags command flags
* @param wagon_removal remove wagons when the resulting chain occupies more tiles than the old did
@ -607,7 +616,8 @@ static CommandCost ReplaceChain(Vehicle **chain, DoCommandFlag flags, bool wagon
return cost;
}
/** Autoreplaces a vehicle
/**
* Autoreplaces a vehicle
* Trains are replaced as a whole chain, free wagons in depot are replaced on their own
* @param tile not used
* @param flags type of operation

12
src/autoreplace_gui.cpp
View File

@ -63,7 +63,8 @@ static int CDECL EngineNumberSorter(const EngineID *a, const EngineID *b)
return r;
}
/** Rebuild the left autoreplace list if an engine is removed or added
/**
* Rebuild the left autoreplace list if an engine is removed or added
* @param e Engine to check if it is removed or added
* @param id_g The group the engine belongs to
* Note: this function only works if it is called either
@ -84,7 +85,8 @@ void InvalidateAutoreplaceWindow(EngineID e, GroupID id_g)
}
}
/** When an engine is made buildable or is removed from being buildable, add/remove it from the build/autoreplace lists
/**
* When an engine is made buildable or is removed from being buildable, add/remove it from the build/autoreplace lists
* @param type The type of engine
*/
void AddRemoveEngineFromAutoreplaceAndBuildWindows(VehicleType type)
@ -105,7 +107,8 @@ class ReplaceVehicleWindow : public Window {
int details_height; ///< Minimal needed height of the details panels (found so far).
RailType sel_railtype; ///< Type of rail tracks selected.
/** Figure out if an engine should be added to a list.
/**
* Figure out if an engine should be added to a list.
* @param e The EngineID.
* @param draw_left If \c true, the left list is drawn (the engines specific to the railtype you selected).
* @param show_engines If \c true, the locomotives are drawn, else the wagons are drawn (never both).
@ -126,7 +129,8 @@ class ReplaceVehicleWindow : public Window {
}
/** Generate an engines list
/**
* Generate an engines list
* @param draw_left true if generating the left list, otherwise false
*/
void GenerateReplaceVehList(bool draw_left)

6
src/bridge.h
View File

@ -15,7 +15,8 @@
#include "gfx_type.h"
#include "tile_cmd.h"
/** This enum is related to the definition of bridge pieces,
/**
* This enum is related to the definition of bridge pieces,
* which is used to determine the proper sprite table to use
* while drawing a given bridge part.
*/
@ -36,7 +37,8 @@ static const uint MAX_BRIDGES = 13;
typedef uint BridgeType;
/** Struct containing information about a single bridge type
/**
* Struct containing information about a single bridge type
*/
struct BridgeSpec {
Year avail_year; ///< the year where it becomes available

3
src/build_vehicle_gui.cpp
View File

@ -711,7 +711,8 @@ int DrawVehiclePurchaseInfo(int left, int right, int y, EngineID engine_number)
return y;
}
/** Engine drawing loop
/**
* Engine drawing loop
* @param type Type of vehicle (VEH_*)
* @param l The left most location of the list
* @param r The right most location of the list

6
src/cargo_type.h
View File

@ -87,7 +87,8 @@ public:
memset(this->amount, 0, sizeof(this->amount));
}
/** Read/write access to an amount of a specific cargo type.
/**
* Read/write access to an amount of a specific cargo type.
* @param cargo Cargo type to access.
*/
FORCEINLINE uint &operator[](CargoID cargo)
@ -95,7 +96,8 @@ public:
return this->amount[cargo];
}
/** Read-only access to an amount of a specific cargo type.
/**
* Read-only access to an amount of a specific cargo type.
* @param cargo Cargo type to access.
*/
FORCEINLINE const uint &operator[](CargoID cargo) const

15
src/cargotype.cpp
View File

@ -22,12 +22,14 @@
CargoSpec CargoSpec::array[NUM_CARGO];
/** Bitmask of cargo types available.
/**
* Bitmask of cargo types available.
* Initialized during a call to #SetupCargoForClimate.
*/
uint32 _cargo_mask;
/** Set up the default cargo types for the given landscape type.
/**
* Set up the default cargo types for the given landscape type.
* @param l Landscape
*/
void SetupCargoForClimate(LandscapeID l)
@ -66,7 +68,8 @@ void SetupCargoForClimate(LandscapeID l)
}
}
/** Get the cargo ID by cargo label.
/**
* Get the cargo ID by cargo label.
* @param cl Cargo type to get.
* @return ID number if the cargo exists, else #CT_INVALID
*/
@ -82,7 +85,8 @@ CargoID GetCargoIDByLabel(CargoLabel cl)
}
/** Find the CargoID of a 'bitnum' value.
/**
* Find the CargoID of a 'bitnum' value.
* @param bitnum 'bitnum' to find.
* @return First CargoID with the given bitnum, or #CT_INVALID if not found or if the provided \a bitnum is invalid.
*/
@ -99,7 +103,8 @@ CargoID GetCargoIDByBitnum(uint8 bitnum)
return CT_INVALID;
}
/** Get sprite for showing cargo of this type.
/**
* Get sprite for showing cargo of this type.
* @return Sprite number to use.
*/
SpriteID CargoSpec::GetCargoIcon() const

3
src/cargotype.h
View File

@ -136,7 +136,8 @@ extern const CargoSpec *_sorted_cargo_specs[NUM_CARGO];
extern uint8 _sorted_cargo_specs_size;
extern uint8 _sorted_standard_cargo_specs_size;
/** Does cargo \a c have cargo class \a cc?
/**
* Does cargo \a c have cargo class \a cc?
* @param c Cargo type.
* @param cc Cargo class.
* @return The type fits in the class.

15
src/company_cmd.cpp
View File

@ -718,7 +718,8 @@ void CompanyNewsInformation::FillData(const Company *c, const Company *other)
}
/** Control the companies: add, delete, etc.
/**
* Control the companies: add, delete, etc.
* @param tile unused
* @param flags operation to perform
* @param p1 various functionality
@ -869,7 +870,8 @@ CommandCost CmdCompanyCtrl(TileIndex tile, DoCommandFlag flags, uint32 p1, uint3
return CommandCost();
}
/** Change the company manager's face.
/**
* Change the company manager's face.
* @param tile unused
* @param flags operation to perform
* @param p1 unused
@ -890,7 +892,8 @@ CommandCost CmdSetCompanyManagerFace(TileIndex tile, DoCommandFlag flags, uint32
return CommandCost();
}
/** Change the company's company-colour
/**
* Change the company's company-colour
* @param tile unused
* @param flags operation to perform
* @param p1 bitstuffed:
@ -999,7 +1002,8 @@ static bool IsUniqueCompanyName(const char *name)
return true;
}
/** Change the name of the company.
/**
* Change the name of the company.
* @param tile unused
* @param flags operation to perform
* @param p1 unused
@ -1042,7 +1046,8 @@ static bool IsUniquePresidentName(const char *name)
return true;
}
/** Change the name of the president.
/**
* Change the name of the president.
* @param tile unused
* @param flags operation to perform
* @param p1 unused

21
src/company_gui.cpp
View File

@ -141,7 +141,8 @@ enum CompanyFinancesWindowWidgets {
CFW_REPAY_LOAN, ///< Decrease loan
};
/** Draw the expenses categories.
/**
* Draw the expenses categories.
* @param r Available space for drawing.
* @note The environment must provide padding at the left and right of \a r.
*/
@ -168,7 +169,8 @@ static void DrawCategories(const Rect &r)
DrawString(r.left, r.right, y + EXP_LINESPACE, STR_FINANCES_TOTAL_CAPTION, TC_FROMSTRING, SA_RIGHT);
}
/** Draw an amount of money.
/**
* Draw an amount of money.
* @param amount Amount of money to draw,
* @param left Left coordinate of the space to draw in.
* @param right Right coordinate of the space to draw in.
@ -185,7 +187,8 @@ static void DrawPrice(Money amount, int left, int right, int top)
DrawString(left, right, top, str, TC_FROMSTRING, SA_RIGHT);
}
/** Draw a column with prices.
/**
* Draw a column with prices.
* @param r Available space for drawing.
* @param year Year being drawn.
* @param tbl Pointer to table of amounts for \a year.
@ -278,7 +281,8 @@ static const NWidgetPart _nested_company_finances_widgets[] = {
EndContainer(),
};
/** Window class displaying the company finances.
/**
* Window class displaying the company finances.
* @todo #money_width should be calculated dynamically.
*/
struct CompanyFinancesWindow : Window {
@ -387,7 +391,8 @@ struct CompanyFinancesWindow : Window {
}
}
/** Setup the widgets in the nested tree, such that the finances window is displayed properly.
/**
* Setup the widgets in the nested tree, such that the finances window is displayed properly.
* @note After setup, the window must be (re-)initialized.
*/
void SetupWidgets()
@ -477,7 +482,8 @@ static const WindowDesc _company_finances_desc(
_nested_company_finances_widgets, lengthof(_nested_company_finances_widgets)
);
/** Open the finances window of a company.
/**
* Open the finances window of a company.
* @param company Company to show finances of.
* @pre is company a valid company.
*/
@ -1145,7 +1151,8 @@ public:
this->UpdateData();
}
/** Select planes to display to the user with the #NWID_SELECTION widgets #SCMFW_WIDGET_SEL_LOADSAVE, #SCMFW_WIDGET_SEL_MALEFEMALE, and #SCMFW_WIDGET_SEL_PARTS.
/**
* Select planes to display to the user with the #NWID_SELECTION widgets #SCMFW_WIDGET_SEL_LOADSAVE, #SCMFW_WIDGET_SEL_MALEFEMALE, and #SCMFW_WIDGET_SEL_PARTS.
* @param advanced Display advanced face management window.
*/
void SelectDisplayPlanes(bool advanced)

6
src/console_internal.h
View File

@ -24,7 +24,8 @@ enum ConsoleHookResult {
CHR_HIDE, ///< Hide the existence of the command.
};
/** --Commands--
/**
* --Commands--
* Commands are commands, or functions. They get executed once and any
* effect they produce are carried out. The arguments to the commands
* are given to them, each input word seperated by a double-quote (") is an argument
@ -41,7 +42,8 @@ struct IConsoleCmd {
IConsoleHook *hook; ///< any special trigger action that needs executing
};
/** --Aliases--
/**
* --Aliases--
* Aliases are like shortcuts for complex functions, variable assignments,
* etc. You can use a simple alias to rename a longer command (eg 'set' for
* 'setting' for example), or concatenate more commands into one

6
src/core/bitmath_func.hpp
View File

@ -34,7 +34,8 @@ static FORCEINLINE uint GB(const T x, const uint8 s, const uint8 n)
return (x >> s) & ((1U << n) - 1);
}
/** Set \a n bits in \a x starting at bit \a s to \a d
/**
* Set \a n bits in \a x starting at bit \a s to \a d
*
* This function sets \a n bits from \a x which started as bit \a s to the value of
* \a d. The parameters \a x, \a s and \a n works the same as the parameters of
@ -59,7 +60,8 @@ static FORCEINLINE T SB(T &x, const uint8 s, const uint8 n, const U d)
return x;
}
/** Add i to n bits of x starting at bit s.
/**
* Add i to n bits of x starting at bit s.
*
* This add the value of i on n bits of x starting at bit s. The parameters x,
* s, i are similar to #GB besides x must be a variable as the result are

9
src/core/enum_type.hpp
View File

@ -40,7 +40,8 @@
FORCEINLINE mask_t operator ~(mask_t m) {return (mask_t)(~(int)m);}
/** Informative template class exposing basic enumeration properties used by several
/**
* Informative template class exposing basic enumeration properties used by several
* other templates below. Here we have only forward declaration. For each enum type
* we will create specialization derived from MakeEnumPropsT<>.
* i.e.:
@ -50,7 +51,8 @@
*/
template <typename Tenum_t> struct EnumPropsT;
/** Helper template class that makes basic properties of given enumeration type visible
/**
* Helper template class that makes basic properties of given enumeration type visible
* from outsize. It is used as base class of several EnumPropsT specializations each
* dedicated to one of commonly used enumeration types.
* @param Tenum_t enumeration type that you want to describe
@ -72,7 +74,8 @@ struct MakeEnumPropsT {
/** In some cases we use byte or uint16 to store values that are defined as enum. It is
/**
* In some cases we use byte or uint16 to store values that are defined as enum. It is
* necessary in order to control the sizeof() such values. Some compilers make enum
* the same size as int (4 or 8 bytes instead of 1 or 2). As a consequence the strict
* compiler type - checking causes errors like:

6
src/core/random_func.hpp
View File

@ -65,7 +65,8 @@ struct SavedRandomSeeds {
Randomizer interactive_random;
};
/** Saves the current seeds
/**
* Saves the current seeds
* @param storage Storage for saving
*/
static inline void SaveRandomSeeds(SavedRandomSeeds *storage)
@ -74,7 +75,8 @@ static inline void SaveRandomSeeds(SavedRandomSeeds *storage)
storage->interactive_random = _interactive_random;
}
/** Restores previously saved seeds
/**
* Restores previously saved seeds
* @param storage Storage where SaveRandomSeeds() stored th seeds
*/
static inline void RestoreRandomSeeds(const SavedRandomSeeds &storage)

18
src/core/smallmap_type.hpp
View File

@ -25,7 +25,8 @@ struct SmallPair {
FORCEINLINE SmallPair(const T &first, const U &second) : first(first), second(second) { }
};
/** Implementation of simple mapping class. Both types have to be POD ("Plain Old Data")!
/**
* Implementation of simple mapping class. Both types have to be POD ("Plain Old Data")!
* It has inherited accessors from SmallVector().
* @see SmallVector
*/
@ -40,7 +41,8 @@ struct SmallMap : SmallVector<SmallPair<T, U>, S> {
/** Data are freed in SmallVector destructor */
FORCEINLINE ~SmallMap() { }
/** Finds given key in this map
/**
* Finds given key in this map
* @param key key to find
* @return &Pair(key, data) if found, this->End() if not
*/
@ -52,7 +54,8 @@ struct SmallMap : SmallVector<SmallPair<T, U>, S> {
return this->End();
}
/** Removes given pair from this map
/**
* Removes given pair from this map
* @param pair pair to remove
* @note it has to be pointer to pair in this map. It is overwritten by the last item.
*/
@ -62,7 +65,8 @@ struct SmallMap : SmallVector<SmallPair<T, U>, S> {
*pair = this->data[--this->items];
}
/** Removes given key from this map
/**
* Removes given key from this map
* @param key key to remove
* @return true iff the key was found
* @note last item is moved to its place, so don't increase your iterator if true is returned!
@ -78,7 +82,8 @@ struct SmallMap : SmallVector<SmallPair<T, U>, S> {
return false;
}
/** Adds new item to this map.
/**
* Adds new item to this map.
* @param key key
* @param data data
* @return true iff the key wasn't already present
@ -92,7 +97,8 @@ struct SmallMap : SmallVector<SmallPair<T, U>, S> {
return true;
}
/** Returns data belonging to this key
/**
* Returns data belonging to this key
* @param key key
* @return data belonging to this key
* @note if this key wasn't present, new entry is created

3
src/debug.cpp
View File

@ -161,7 +161,8 @@ void SetDebugString(const char *s)
}
}
/** Print out the current debug-level
/**
* Print out the current debug-level
* Just return a string with the values of all the debug categorites
* @return string with debug-levels
*/

18
src/depot_gui.cpp
View File

@ -159,7 +159,8 @@ static void TrainDepotMoveVehicle(const Vehicle *wagon, VehicleID sel, const Veh
DoCommandP(v->tile, v->index + ((wagon == NULL ? INVALID_VEHICLE : wagon->index) << 16), _ctrl_pressed ? 1 : 0, CMD_MOVE_RAIL_VEHICLE | CMD_MSG(STR_ERROR_CAN_T_MOVE_VEHICLE));
}
/** Array containing the cell size in pixels of the #DEPOT_WIDGET_MATRIX widget for each vehicle type.
/**
* Array containing the cell size in pixels of the #DEPOT_WIDGET_MATRIX widget for each vehicle type.
* @note The train vehicle type uses the entire row for each train. */
static Dimension _base_block_sizes[4];
@ -194,7 +195,8 @@ static void InitBlocksizeForShipAircraft(VehicleType type)
_base_block_sizes[type].height = max(GetVehicleHeight(type), max_height);
}
/** Set the size of the blocks in the window so we can be sure that they are big enough for the vehicle sprites in the current game.
/**
* Set the size of the blocks in the window so we can be sure that they are big enough for the vehicle sprites in the current game.
* @note Calling this function once for each game is enough. */
void InitDepotWindowBlockSizes()
{
@ -244,7 +246,8 @@ struct DepotWindow : Window {
DeleteWindowById(WC_BUILD_VEHICLE, this->window_number);
}
/** Draw a vehicle in the depot window in the box with the top left corner at x,y.
/**
* Draw a vehicle in the depot window in the box with the top left corner at x,y.
* @param v Vehicle to draw.
* @param left Left side of the box to draw in.
* @param right Right side of the box to draw in.
@ -457,7 +460,8 @@ struct DepotWindow : Window {
return MODE_DRAG_VEHICLE;
}
/** Handle click in the depot matrix.
/**
* Handle click in the depot matrix.
* @param x Horizontal position in the matrix widget in pixels.
* @param y Vertical position in the matrix widget in pixels.
*/
@ -1031,7 +1035,8 @@ static void DepotSellAllConfirmationCallback(Window *win, bool confirmed)
}
}
/** Opens a depot window
/**
* Opens a depot window
* @param tile The tile where the depot/hangar is located
* @param type The type of vehicles in the depot
*/
@ -1051,7 +1056,8 @@ void ShowDepotWindow(TileIndex tile, VehicleType type)
new DepotWindow(desc, tile, type);
}
/** Removes the highlight of a vehicle in a depot window
/**
* Removes the highlight of a vehicle in a depot window
* @param *v Vehicle to remove all highlights from
*/
void DeleteDepotHighlightOfVehicle(const Vehicle *v)

21
src/disaster_cmd.cpp
View File

@ -7,7 +7,8 @@
* 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 disaster_cmd.cpp
/**
* @file disaster_cmd.cpp
* All disaster/easter egg vehicles are handled here.
* The general flow of control for the disaster vehicles is as follows:
* <ol>
@ -128,7 +129,8 @@ static void DisasterVehicleUpdateImage(DisasterVehicle *v)
v->cur_image = img;
}
/** Initialize a disaster vehicle. These vehicles are of type VEH_DISASTER, are unclickable
/**
* Initialize a disaster vehicle. These vehicles are of type VEH_DISASTER, are unclickable
* and owned by nobody */
static void InitializeDisasterVehicle(DisasterVehicle *v, int x, int y, byte z, Direction direction, byte subtype)
{
@ -670,7 +672,8 @@ bool DisasterVehicle::Tick()
typedef void DisasterInitProc();
/** Zeppeliner which crashes on a small airport if one found,
/**
* Zeppeliner which crashes on a small airport if one found,
* otherwise crashes on a random tile */
static void Disaster_Zeppeliner_Init()
{
@ -698,7 +701,8 @@ static void Disaster_Zeppeliner_Init()
}
/** Ufo which flies around aimlessly from the middle of the map a bit
/**
* Ufo which flies around aimlessly from the middle of the map a bit
* until it locates a road vehicle which it targets and then destroys */
static void Disaster_Small_Ufo_Init()
{
@ -844,7 +848,8 @@ static void Disaster_Big_Submarine_Init()
}
/** Coal mine catastrophe, destroys a stretch of 30 tiles of
/**
* Coal mine catastrophe, destroys a stretch of 30 tiles of
* land in a certain direction */
static void Disaster_CoalMine_Init()
{
@ -927,7 +932,8 @@ void StartupDisasters()
ResetDisasterDelay();
}
/** Marks all disasters targeting this industry in such a way
/**
* Marks all disasters targeting this industry in such a way
* they won't call Industry::Get(v->dest_tile) on invalid industry anymore.
* @param i deleted industry
*/
@ -943,7 +949,8 @@ void ReleaseDisastersTargetingIndustry(IndustryID i)
}
}
/** Notify disasters that we are about to delete a vehicle. So make them head elsewhere.
/**
* Notify disasters that we are about to delete a vehicle. So make them head elsewhere.
* @param vehicle deleted vehicle
*/
void ReleaseDisastersTargetingVehicle(VehicleID vehicle)

3
src/driver.cpp
View File

@ -195,7 +195,8 @@ char *DriverFactoryBase::GetDriversInfo(char *p, const char *last)
return p;
}
/** Frees memory used for this->name
/**
* Frees memory used for this->name
*/
DriverFactoryBase::~DriverFactoryBase()
{

3
src/driver.h
View File

@ -79,7 +79,8 @@ public:
virtual ~DriverFactoryBase();
/** Shuts down all active drivers
/**
* Shuts down all active drivers
*/
static void ShutdownDrivers()
{

12
src/economy.cpp
View File

@ -156,7 +156,8 @@ Money CalculateCompanyValue(const Company *c, bool including_loan)
return max(value, (Money)1);
}
/** if update is set to true, the economy is updated with this score
/**
* if update is set to true, the economy is updated with this score
* (also the house is updated, should only be true in the on-tick event)
* @param update the economy with calculated score
* @param c company been evaluated
@ -1485,7 +1486,8 @@ static void DoAcquireCompany(Company *c)
extern int GetAmountOwnedBy(const Company *c, Owner owner);
/** Acquire shares in an opposing company.
/**
* Acquire shares in an opposing company.
* @param tile unused
* @param flags type of operation
* @param p1 company to buy the shares from
@ -1532,7 +1534,8 @@ CommandCost CmdBuyShareInCompany(TileIndex tile, DoCommandFlag flags, uint32 p1,
return cost;
}
/** Sell shares in an opposing company.
/**
* Sell shares in an opposing company.
* @param tile unused
* @param flags type of operation
* @param p1 company to sell the shares from
@ -1565,7 +1568,8 @@ CommandCost CmdSellShareInCompany(TileIndex tile, DoCommandFlag flags, uint32 p1
return CommandCost(EXPENSES_OTHER, cost);
}
/** Buy up another company.
/**
* Buy up another company.
* When a competing company is gone bankrupt you get the chance to purchase
* that company.
* @todo currently this only works for AI companies

9
src/elrail.cpp
View File

@ -7,7 +7,8 @@
* 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 elrail.cpp
/**
* @file elrail.cpp
* This file deals with displaying wires and pylons for electric railways.
* <h2>Basics</h2>
*
@ -182,7 +183,8 @@ static inline SpriteID GetPylonBase(TileIndex tile, bool upper_halftile = false)
return pylons == 0 ? SPR_PYLON_BASE : pylons;
}
/** Corrects the tileh for certain tile types. Returns an effective tileh for the track on the tile.
/**
* Corrects the tileh for certain tile types. Returns an effective tileh for the track on the tile.
* @param tile The tile to analyse
* @param *tileh the tileh
*/
@ -258,7 +260,8 @@ void DrawCatenaryOnTunnel(const TileInfo *ti)
);
}
/** Draws wires and, if required, pylons on a given tile
/**
* Draws wires and, if required, pylons on a given tile
* @param ti The Tileinfo to draw the tile for
*/
static void DrawCatenaryRailway(const TileInfo *ti)

3
src/endian_check.cpp
View File

@ -7,7 +7,8 @@
* 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 endian_check.cpp
/**
* @file endian_check.cpp
* This pretty simple file checks if the system is LITTLE_ENDIAN or BIG_ENDIAN
* it does that by putting a 1 and a 0 in an array, and read it out as one
* number. If it is 1, it is LITTLE_ENDIAN, if it is 256, it is BIG_ENDIAN

15
src/engine.cpp
View File

@ -38,7 +38,8 @@ INSTANTIATE_POOL_METHODS(Engine)
EngineOverrideManager _engine_mngr;
/** Year that engine aging stops. Engines will not reduce in reliability
/**
* Year that engine aging stops. Engines will not reduce in reliability
* and no more engines will be introduced */
static Year _year_engine_aging_stops;
@ -399,7 +400,8 @@ EngineID EngineOverrideManager::GetID(VehicleType type, uint16 grf_local_id, uin
return INVALID_ENGINE;
}
/** Sets cached values in Company::num_vehicles and Group::num_vehicles
/**
* Sets cached values in Company::num_vehicles and Group::num_vehicles
*/
void SetCachedEngineCounts()
{
@ -653,7 +655,8 @@ void EnginesDailyLoop()
}
}
/** Accept an engine prototype. XXX - it is possible that the top-company
/**
* Accept an engine prototype. XXX - it is possible that the top-company
* changes while you are waiting to accept the offer? Then it becomes invalid
* @param tile unused
* @param flags operation to perfom
@ -766,7 +769,8 @@ static bool IsUniqueEngineName(const char *name)
return true;
}
/** Rename an engine.
/**
* Rename an engine.
* @param tile unused
* @param flags operation to perfom
* @param p1 engine ID to rename
@ -802,7 +806,8 @@ CommandCost CmdRenameEngine(TileIndex tile, DoCommandFlag flags, uint32 p1, uint
}
/** Check if an engine is buildable.
/**
* Check if an engine is buildable.
* @param engine index of the engine to check.
* @param type the type the engine should be.
* @param company index of the company.

9
src/engine_gui.cpp
View File

@ -24,7 +24,8 @@
#include "table/strings.h"
/** Return the category of an engine.
/**
* Return the category of an engine.
* @param engine Engine to examine.
* @return String describing the category ("road veh", "train". "airplane", or "ship") of the engine.
*/
@ -292,7 +293,8 @@ void DrawVehicleEngine(int left, int right, int preferred_x, int y, EngineID eng
}
}
/** Sort all items using quick sort and given 'CompareItems' function
/**
* Sort all items using quick sort and given 'CompareItems' function
* @param el list to be sorted
* @param compare function for evaluation of the quicksort
*/
@ -305,7 +307,8 @@ void EngList_Sort(GUIEngineList *el, EngList_SortTypeFunction compare)
QSortT(el->Begin(), size, compare);
}
/** Sort selected range of items (on indices @ <begin, begin+num_items-1>)
/**
* Sort selected range of items (on indices @ <begin, begin+num_items-1>)
* @param el list to be sorted
* @param compare function for evaluation of the quicksort
* @param begin start of sorting

3
src/engine_type.h
View File

@ -103,7 +103,8 @@ struct RoadVehicleInfo {
uint8 air_drag; ///< Coefficient of air drag
};
/** Information about a vehicle
/**
* Information about a vehicle
* @see table/engines.h
*/
struct EngineInfo {

6
src/fios.cpp
View File

@ -7,7 +7,8 @@
* 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 fios.cpp
/**
* @file fios.cpp
* This file contains functions for building file lists for the save/load dialogs.
*/
@ -262,7 +263,8 @@ bool FiosFileScanner::AddFile(const char *filename, size_t basepath_length)
}
/** Fill the list of the files in a directory, according to some arbitrary rule.
/**
* Fill the list of the files in a directory, according to some arbitrary rule.
* @param mode The mode we are in. Some modes don't allow 'parent'.
* @param callback_proc The function that is called where you need to do the filtering.
* @param subdir The directory from where to start (global) searching.

3
src/fios_gui.cpp
View File

@ -696,7 +696,8 @@ static const WindowDesc _save_dialog_desc(
_nested_save_dialog_widgets, lengthof(_nested_save_dialog_widgets)
);
/** These values are used to convert the file/operations mode into a corresponding file type.
/**
* These values are used to convert the file/operations mode into a corresponding file type.
* So each entry, as expressed by the related comment, is based on the enum */
static const FileType _file_modetotype[] = {
FT_SAVEGAME, ///< used for SLD_LOAD_GAME

3
src/fontcache.cpp
View File

@ -42,7 +42,8 @@ FreeTypeSettings _freetype;
static const byte FACE_COLOUR = 1;
static const byte SHADOW_COLOUR = 2;
/** Get the font loaded into a Freetype face by using a font-name.
/**
* Get the font loaded into a Freetype face by using a font-name.
* If no appropiate font is found, the function returns an error */
#ifdef WIN32
#include <windows.h>

78
src/gamelog.cpp
View File

@ -39,7 +39,8 @@ uint _gamelog_actions = 0; ///< number of actions
static LoggedAction *_current_action = NULL; ///< current action we are logging, NULL when there is no action active
/** Stores information about new action, but doesn't allocate it
/**
* Stores information about new action, but doesn't allocate it
* Action is allocated only when there is at least one change
* @param at type of action
*/
@ -49,7 +50,8 @@ void GamelogStartAction(GamelogActionType at)
_gamelog_action_type = at;
}
/** Stops logging of any changes
/**
* Stops logging of any changes
*/
void GamelogStopAction()
{
@ -63,7 +65,8 @@ void GamelogStopAction()
if (print) GamelogPrintDebug(5);
}
/** Resets and frees all memory allocated - used before loading or starting a new game
/**
* Resets and frees all memory allocated - used before loading or starting a new game
*/
void GamelogReset()
{
@ -103,7 +106,8 @@ static void AddDebugText(char *buf, const char *s, ...)
}
/** Prints GRF filename if found
/**
* Prints GRF filename if found
* @param buf The location in the _dbgofs buffer to draw
* @param grfid GRF which filename to print
*/
@ -116,7 +120,8 @@ static void PrintGrfFilename(char *buf, uint grfid)
AddDebugText(buf, ", filename: %s", gc->filename);
}
/** Prints GRF ID, checksum and filename if found
/**
* Prints GRF ID, checksum and filename if found
* @param buf The location in the _dbgofs buffer to draw
* @param grfid GRF ID
* @param md5sum array of md5sum to print
@ -292,7 +297,8 @@ static void GamelogPrintDebugProc(const char *s)
}
/** Prints gamelog to debug output. Code is executed even when
/**
* Prints gamelog to debug output. Code is executed even when
* there will be no output. It is called very seldom, so it
* doesn't matter that much. At least it gives more uniform code...
* @param level debug level we need to print stuff
@ -304,7 +310,8 @@ void GamelogPrintDebug(int level)
}
/** Allocates new LoggedChange and new LoggedAction if needed.
/**
* Allocates new LoggedChange and new LoggedAction if needed.
* If there is no action active, NULL is returned.
* @param ct type of change
* @return new LoggedChange, or NULL if there is no action active
@ -332,7 +339,8 @@ static LoggedChange *GamelogChange(GamelogChangeType ct)
}
/** Logs a emergency savegame
/**
* Logs a emergency savegame
*/
void GamelogEmergency()
{
@ -343,7 +351,8 @@ void GamelogEmergency()
GamelogStopAction();
}
/** Finds out if current game is a loaded emergency savegame.
/**
* Finds out if current game is a loaded emergency savegame.
*/
bool GamelogTestEmergency()
{
@ -360,7 +369,8 @@ bool GamelogTestEmergency()
return (emergency != NULL);
}
/** Logs a change in game revision
/**
* Logs a change in game revision
*/
void GamelogRevision()
{
@ -376,7 +386,8 @@ void GamelogRevision()
lc->revision.newgrf = _openttd_newgrf_version;
}
/** Logs a change in game mode (scenario editor or game)
/**
* Logs a change in game mode (scenario editor or game)
*/
void GamelogMode()
{
@ -389,7 +400,8 @@ void GamelogMode()
lc->mode.landscape = _settings_game.game_creation.landscape;
}
/** Logs loading from savegame without gamelog
/**
* Logs loading from savegame without gamelog
*/
void GamelogOldver()
{
@ -402,7 +414,8 @@ void GamelogOldver()
lc->oldver.version = (_savegame_type == SGT_OTTD ? ((uint32)_sl_version << 8 | _sl_minor_version) : _ttdp_version);
}
/** Logs change in game settings. Only non-networksafe settings are logged
/**
* Logs change in game settings. Only non-networksafe settings are logged
* @param name setting name
* @param oldval old setting value
* @param newval new setting value
@ -420,7 +433,8 @@ void GamelogSetting(const char *name, int32 oldval, int32 newval)
}
/** Finds out if current revision is different than last revision stored in the savegame.
/**
* Finds out if current revision is different than last revision stored in the savegame.
* Appends GLCT_REVISION when the revision string changed
*/
void GamelogTestRevision()
@ -442,7 +456,8 @@ void GamelogTestRevision()
}
}
/** Finds last stored game mode or landscape.
/**
* Finds last stored game mode or landscape.
* Any change is logged
*/
void GamelogTestMode()
@ -461,7 +476,8 @@ void GamelogTestMode()
}
/** Logs triggered GRF bug.
/**
* Logs triggered GRF bug.
* @param grfid ID of problematic GRF
* @param bug type of bug, @see enum GRFBugs
* @param data additional data
@ -478,7 +494,8 @@ static void GamelogGRFBug(uint32 grfid, byte bug, uint64 data)
lc->grfbug.bug = bug;
}
/** Logs GRF bug - rail vehicle has different length after reversing.
/**
* Logs GRF bug - rail vehicle has different length after reversing.
* Ensures this is logged only once for each GRF and engine type
* This check takes some time, but it is called pretty seldom, so it
* doesn't matter that much (ideally it shouldn't be called at all).
@ -507,7 +524,8 @@ bool GamelogGRFBugReverse(uint32 grfid, uint16 internal_id)
}
/** Decides if GRF should be logged
/**
* Decides if GRF should be logged
* @param g grf to determine
* @return true iff GRF is not static and is loaded
*/
@ -516,7 +534,8 @@ static inline bool IsLoggableGrfConfig(const GRFConfig *g)
return !HasBit(g->flags, GCF_STATIC) && g->status != GCS_NOT_FOUND;
}
/** Logs removal of a GRF
/**
* Logs removal of a GRF
* @param grfid ID of removed GRF
*/
void GamelogGRFRemove(uint32 grfid)
@ -529,7 +548,8 @@ void GamelogGRFRemove(uint32 grfid)
lc->grfrem.grfid = grfid;
}
/** Logs adding of a GRF
/**
* Logs adding of a GRF
* @param newg added GRF
*/
void GamelogGRFAdd(const GRFConfig *newg)
@ -544,7 +564,8 @@ void GamelogGRFAdd(const GRFConfig *newg)
lc->grfadd = newg->ident;
}
/** Logs loading compatible GRF
/**
* Logs loading compatible GRF
* (the same ID, but different MD5 hash)
* @param newg new (updated) GRF
*/
@ -558,7 +579,8 @@ void GamelogGRFCompatible(const GRFIdentifier *newg)
lc->grfcompat = *newg;
}
/** Logs changing GRF order
/**
* Logs changing GRF order
* @param grfid GRF that is moved
* @param offset how far it is moved, positive = moved down
*/
@ -573,7 +595,8 @@ static void GamelogGRFMove(uint32 grfid, int32 offset)
lc->grfmove.offset = offset;
}
/** Logs change in GRF parameters.
/**
* Logs change in GRF parameters.
* Details about parameters changed are not stored
* @param grfid ID of GRF to store
*/
@ -587,7 +610,8 @@ static void GamelogGRFParameters(uint32 grfid)
lc->grfparam.grfid = grfid;
}
/** Logs adding of list of GRFs.
/**
* Logs adding of list of GRFs.
* Useful when old savegame is loaded or when new game is started
* @param newg head of GRF linked list
*/
@ -606,7 +630,8 @@ struct GRFList {
const GRFConfig *grf[];
};
/** Generates GRFList
/**
* Generates GRFList
* @param grfc head of GRF linked list
*/
static GRFList *GenerateGRFList(const GRFConfig *grfc)
@ -626,7 +651,8 @@ static GRFList *GenerateGRFList(const GRFConfig *grfc)
return list;
}
/** Compares two NewGRF lists and logs any change
/**
* Compares two NewGRF lists and logs any change
* @param oldc original GRF list
* @param newc new GRF list
*/

27
src/gfx.cpp
View File

@ -68,7 +68,8 @@ struct DrawStringParams {
DrawStringParams(TextColour colour) : fontsize(FS_NORMAL), cur_colour(colour), prev_colour(colour) {}
/** Switch to new colour \a c.
/**
* Switch to new colour \a c.
* @param c New colour to use.
*/
FORCEINLINE void SetColour(TextColour c)
@ -84,7 +85,8 @@ struct DrawStringParams {
Swap(this->cur_colour, this->prev_colour);
}
/** Switch to using a new font \a f.
/**
* Switch to using a new font \a f.
* @param f New font to use.
*/
FORCEINLINE void SetFontSize(FontSize f)
@ -358,7 +360,8 @@ static UChar *HandleBiDiAndArabicShapes(UChar *buffer)
#endif /* WITH_ICU */
/** Truncate a given string to a maximum width if neccessary.
/**
* Truncate a given string to a maximum width if neccessary.
* If the string is truncated, add three dots ('...') to show this.
* @param *str string that is checked and possibly truncated
* @param maxw maximum width in pixels of the string
@ -758,7 +761,8 @@ end_of_inner_loop:
}
/** Calculates height of string (in pixels). Accepts multiline string with '\0' as separators.
/**
* Calculates height of string (in pixels). Accepts multiline string with '\0' as separators.
* @param src string to check
* @param num number of extra lines (output of FormatStringLinebreaks())
* @param start_fontsize Fontsize to start the text with
@ -787,7 +791,8 @@ static int GetMultilineStringHeight(const char *src, int num, FontSize start_fon
}
/** Calculates height of string (in pixels). The string is changed to a multiline string if needed.
/**
* Calculates height of string (in pixels). The string is changed to a multiline string if needed.
* @param str string to check
* @param maxw maximum string width
* @return height of pixels of string when it is drawn
@ -803,7 +808,8 @@ int GetStringHeight(StringID str, int maxw)
return GetMultilineStringHeight(buffer, GB(tmp, 0, 16), FS_NORMAL);
}
/** Calculate string bounding box for multi-line strings.
/**
* Calculate string bounding box for multi-line strings.
* @param str String to check.
* @param suggestion Suggested bounding box.
* @return Bounding box for the multi-line string, may be bigger than \a suggestion.
@ -956,7 +962,8 @@ int DrawStringMultiLine(int left, int right, int top, int bottom, StringID str,
return DrawStringMultiLine(left, right, top, bottom, buffer, lastof(buffer), colour, align, underline);
}
/** Return the string dimension in pixels. The height and width are returned
/**
* Return the string dimension in pixels. The height and width are returned
* in a single Dimension value. TINYFONT, BIGFONT modifiers are only
* supported as the first character of the string. The returned dimensions
* are therefore a rough estimation correct for all the current strings
@ -1027,7 +1034,8 @@ void DrawCharCentered(WChar c, int x, int y, TextColour colour)
GfxMainBlitter(GetGlyph(FS_NORMAL, c), x - GetCharacterWidth(FS_NORMAL, c) / 2, y, BM_COLOUR_REMAP);
}
/** Draw a string at the given coordinates with the given colour.
/**
* Draw a string at the given coordinates with the given colour.
* While drawing the string, parse it in case some formatting is specified,
* like new colour, new size or even positionning.
* @param string The string to draw. This is already bidi reordered.
@ -1706,7 +1714,8 @@ void MarkWholeScreenDirty()
SetDirtyBlocks(0, 0, _screen.width, _screen.height);
}
/** Set up a clipping area for only drawing into a certain area. To do this,
/**
* Set up a clipping area for only drawing into a certain area. To do this,
* Fill a DrawPixelInfo object with the supplied relative rectangle, backup
* the original (calling) _cur_dpi and assign the just returned DrawPixelInfo
* _cur_dpi. When you are done, give restore _cur_dpi's original value

6
src/graph_gui.cpp
View File

@ -261,7 +261,8 @@ protected:
return current_interval;
}
/** Get width for Y labels.
/**
* Get width for Y labels.
* @param current_interval Interval that contains all of the graph data.
* @param num_hori_lines Number of horizontal lines to be drawn.
*/
@ -1519,7 +1520,8 @@ struct PerformanceRatingDetailWindow : Window {
CompanyID PerformanceRatingDetailWindow::company = INVALID_COMPANY;
/** Make a vertical list of panels for outputting score details.
/**
* Make a vertical list of panels for outputting score details.
* @param biggest_index Storage for collecting the biggest index used in the returned tree.
* @return Panel with performance details.
* @post \c *biggest_index contains the largest used index in the tree.

6
src/highscore_gui.cpp
View File

@ -217,7 +217,8 @@ static const WindowDesc _endgame_desc(
_nested_highscore_widgets, lengthof(_nested_highscore_widgets)
);
/** Show the highscore table for a given difficulty. When called from
/**
* Show the highscore table for a given difficulty. When called from
* endgame ranking is set to the top5 element that was newly added
* and is thus highlighted */
void ShowHighscoreTable(int difficulty, int8 ranking)
@ -226,7 +227,8 @@ void ShowHighscoreTable(int difficulty, int8 ranking)
new HighScoreWindow(&_highscore_desc, difficulty, ranking);
}
/** Show the endgame victory screen in 2050. Update the new highscore
/**
* Show the endgame victory screen in 2050. Update the new highscore
* if it was high enough */
void ShowEndGameChart()
{

6
src/house.h
View File

@ -18,7 +18,8 @@
#include "date_type.h"
#include "house_type.h"
/** Simple value that indicates the house has reached the final stage of
/**
* Simple value that indicates the house has reached the final stage of
* construction. */
static const byte TOWN_HOUSE_COMPLETED = 3;
@ -27,7 +28,8 @@ static const HouseID NEW_HOUSE_OFFSET = 110;
static const HouseID HOUSE_MAX = 512;
static const HouseID INVALID_HOUSE_ID = 0xFFFF;
/** There can only be as many classes as there are new houses, plus one for
/**
* There can only be as many classes as there are new houses, plus one for
* NO_CLASS, as the original houses don't have classes. */
static const uint HOUSE_CLASS_MAX = HOUSE_MAX - NEW_HOUSE_OFFSET + 1;

57
src/industry_cmd.cpp
View File

@ -62,7 +62,8 @@ uint16 Industry::counts[NUM_INDUSTRYTYPES];
IndustrySpec _industry_specs[NUM_INDUSTRYTYPES];
IndustryTileSpec _industry_tile_specs[NUM_INDUSTRYTILES];
/** This function initialize the spec arrays of both
/**
* This function initialize the spec arrays of both
* industry and industry tiles.
* It adjusts the enabling of the industry too, based on climate availability.
* This will allow for clearer testings */
@ -1119,7 +1120,8 @@ void OnTick_Industry()
}
}
/** Check the conditions of #CHECK_NOTHING (Always succeeds).
/**
* Check the conditions of #CHECK_NOTHING (Always succeeds).
* @param tile %Tile to perform the checking.
* @return Succeeded or failed command.
*/
@ -1128,7 +1130,8 @@ static CommandCost CheckNewIndustry_NULL(TileIndex tile)
return CommandCost();
}
/** Check the conditions of #CHECK_FOREST (Industry should be build above snow-line in arctic climate).
/**
* Check the conditions of #CHECK_FOREST (Industry should be build above snow-line in arctic climate).
* @param tile %Tile to perform the checking.
* @return Succeeded or failed command.
*/
@ -1142,7 +1145,8 @@ static CommandCost CheckNewIndustry_Forest(TileIndex tile)
return CommandCost();
}
/** Check the conditions of #CHECK_REFINERY (Industry should be positioned near edge of the map).
/**
* Check the conditions of #CHECK_REFINERY (Industry should be positioned near edge of the map).
* @param tile %Tile to perform the checking.
* @return Succeeded or failed command.
*/
@ -1156,7 +1160,8 @@ static CommandCost CheckNewIndustry_OilRefinery(TileIndex tile)
extern bool _ignore_restrictions;
/** Check the conditions of #CHECK_OIL_RIG (Industries at sea should be positioned near edge of the map).
/**
* Check the conditions of #CHECK_OIL_RIG (Industries at sea should be positioned near edge of the map).
* @param tile %Tile to perform the checking.
* @return Succeeded or failed command.
*/
@ -1169,7 +1174,8 @@ static CommandCost CheckNewIndustry_OilRig(TileIndex tile)
return_cmd_error(STR_ERROR_CAN_ONLY_BE_POSITIONED);
}
/** Check the conditions of #CHECK_FARM (Industry should be below snow-line in arctic).
/**
* Check the conditions of #CHECK_FARM (Industry should be below snow-line in arctic).
* @param tile %Tile to perform the checking.
* @return Succeeded or failed command.
*/
@ -1183,7 +1189,8 @@ static CommandCost CheckNewIndustry_Farm(TileIndex tile)
return CommandCost();
}
/** Check the conditions of #CHECK_PLANTATION (Industry should NOT be in the desert).
/**
* Check the conditions of #CHECK_PLANTATION (Industry should NOT be in the desert).
* @param tile %Tile to perform the checking.
* @return Succeeded or failed command.
*/
@ -1195,7 +1202,8 @@ static CommandCost CheckNewIndustry_Plantation(TileIndex tile)
return CommandCost();
}
/** Check the conditions of #CHECK_WATER (Industry should be in the desert).
/**
* Check the conditions of #CHECK_WATER (Industry should be in the desert).
* @param tile %Tile to perform the checking.
* @return Succeeded or failed command.
*/
@ -1207,7 +1215,8 @@ static CommandCost CheckNewIndustry_Water(TileIndex tile)
return CommandCost();
}
/** Check the conditions of #CHECK_LUMBERMILL (Industry should be in the rain forest).
/**
* Check the conditions of #CHECK_LUMBERMILL (Industry should be in the rain forest).
* @param tile %Tile to perform the checking.
* @return Succeeded or failed command.
*/
@ -1219,7 +1228,8 @@ static CommandCost CheckNewIndustry_Lumbermill(TileIndex tile)
return CommandCost();
}
/** Check the conditions of #CHECK_BUBBLEGEN (Industry should be in low land).
/**
* Check the conditions of #CHECK_BUBBLEGEN (Industry should be in low land).
* @param tile %Tile to perform the checking.
* @return Succeeded or failed command.
*/
@ -1231,7 +1241,8 @@ static CommandCost CheckNewIndustry_BubbleGen(TileIndex tile)
return CommandCost();
}
/** Industrytype check function signature.
/**
* Industrytype check function signature.
* @param tile %Tile to check.
* @return Succeeded or failed command.
*/
@ -1250,7 +1261,8 @@ static CheckNewIndustryProc * const _check_new_industry_procs[CHECK_END] = {
CheckNewIndustry_OilRig, ///< CHECK_OIL_RIG
};
/** Find a town for the industry, while checking for multiple industries in the same town.
/**
* Find a town for the industry, while checking for multiple industries in the same town.
* @param tile Position of the industry to build.
* @param type Industry type.
* @param [out] town Pointer to return town for the new industry, \c NULL is written if no good town can be found.
@ -1293,7 +1305,8 @@ bool IsSlopeRefused(Slope current, Slope refused)
return false;
}
/** Are the tiles of the industry free?
/**
* Are the tiles of the industry free?
* @param tile Position to check.
* @param it Industry tiles table.
* @param itspec_index The index of the itsepc to build/fund
@ -1374,7 +1387,8 @@ static CommandCost CheckIfIndustryTilesAreFree(TileIndex tile, const IndustryTil
return_cmd_error(STR_ERROR_SITE_UNSUITABLE);
}
/** Is the industry allowed to be built at this place for the town?
/**
* Is the industry allowed to be built at this place for the town?
* @param tile Tile to construct the industry.
* @param type Type of the industry.
* @param t Town authority that the industry belongs to.
@ -1494,7 +1508,8 @@ static bool CheckIfCanLevelIndustryPlatform(TileIndex tile, DoCommandFlag flags,
}
/** Check that the new industry is far enough from conflicting industries.
/**
* Check that the new industry is far enough from conflicting industries.
* @param tile Tile to construct the industry.
* @param type Type of the new industry.
* @return Succeeded or failed command.
@ -1517,7 +1532,8 @@ static CommandCost CheckIfFarEnoughFromConflictingIndustry(TileIndex tile, int t
return CommandCost();
}
/** Production level maximum, minimum and default values.
/**
* Production level maximum, minimum and default values.
* It is not a value been really used in order to change, but rather an indicator
* of how the industry is behaving. */
enum ProductionLevels {
@ -1661,7 +1677,8 @@ static void DoCreateNewIndustry(Industry *i, TileIndex tile, IndustryType type,
Station::RecomputeIndustriesNearForAll();
}
/** Helper function for Build/Fund an industry
/**
* Helper function for Build/Fund an industry
* @param tile tile where industry is built
* @param type of industry to build
* @param flags of operations to conduct
@ -1720,7 +1737,8 @@ static CommandCost CreateNewIndustryHelper(TileIndex tile, IndustryType type, Do
return CommandCost();
}
/** Build/Fund an industry
/**
* Build/Fund an industry
* @param tile tile where industry is built
* @param flags of operations to conduct
* @param p1 various bitstuffed elements
@ -2167,7 +2185,8 @@ static void ReportNewsProductionChangeIndustry(Industry *ind, CargoID type, int
static const uint PERCENT_TRANSPORTED_60 = 153;
static const uint PERCENT_TRANSPORTED_80 = 204;
/** Change industry production or do closure
/**
* Change industry production or do closure
* @param i Industry for which changes are performed
* @param monthly true if it's the monthly call, false if it's the random call
*/

9
src/industry_gui.cpp
View File

@ -121,7 +121,8 @@ static int CDECL IndustryTypeNameSorter(const IndustryType *a, const IndustryTyp
return (r != 0) ? r : (*a - *b);
}
/** Initialize the list of sorted industry types.
/**
* Initialize the list of sorted industry types.
*/
void SortIndustryTypes()
{
@ -134,7 +135,8 @@ void SortIndustryTypes()
QSortT(_sorted_industry_types, NUM_INDUSTRYTYPES, &IndustryTypeNameSorter);
}
/** Command callback. In case of failure to build an industry, show an error message.
/**
* Command callback. In case of failure to build an industry, show an error message.
* @param result Result of the command.
* @param tile Tile where the industry is placed.
* @param p1 Additional data of the #CMD_BUILD_INDUSTRY command.
@ -665,7 +667,8 @@ public:
}
}
/** Draw the text in the #IVW_INFO panel.
/**
* Draw the text in the #IVW_INFO panel.
* @param left Left edge of the panel.
* @param right Right edge of the panel.
* @param top Top edge of the panel.

3
src/industrytype.h
View File

@ -34,7 +34,8 @@ enum IndustryLifeType {
INDUSTRYLIFE_PROCESSING = 1 << 2, ///< Like factories
};
/** Available procedures to check whether an industry may build at a given location.
/**
* Available procedures to check whether an industry may build at a given location.
* @see CheckNewIndustryProc, _check_new_industry_procs[]
*/
enum CheckProc {

12
src/landscape.cpp
View File

@ -45,7 +45,8 @@ extern const TileTypeProcs
_tile_type_tunnelbridge_procs,
_tile_type_unmovable_procs;
/** Tile callback functions for each type of tile.
/**
* Tile callback functions for each type of tile.
* @ingroup TileCallbackGroup
* @see TileType */
const TileTypeProcs * const _tile_type_procs[16] = {
@ -485,7 +486,8 @@ void DoClearSquare(TileIndex tile)
MarkTileDirtyByTile(tile);
}
/** Returns information about trackdirs and signal states.
/**
* Returns information about trackdirs and signal states.
* If there is any trackbit at 'side', return all trackdirbits.
* For TRANSPORT_ROAD, return no trackbits if there is no roadbit (of given subtype) at given side.
* @param tile tile to get info about
@ -588,7 +590,8 @@ void ClearSnowLine()
_snow_line = NULL;
}
/** Clear a piece of landscape
/**
* Clear a piece of landscape
* @param tile tile to clear
* @param flags of operation to conduct
* @param p1 unused
@ -601,7 +604,8 @@ CommandCost CmdLandscapeClear(TileIndex tile, DoCommandFlag flags, uint32 p1, ui
return _tile_type_procs[GetTileType(tile)]->clear_tile_proc(tile, flags);
}
/** Clear a big piece of landscape
/**
* Clear a big piece of landscape
* @param tile end tile of area dragging
* @param flags of operation to conduct
* @param p1 start tile of area dragging

3
src/landscape.h
View File

@ -18,7 +18,8 @@
static const uint SNOW_LINE_MONTHS = 12; ///< Number of months in the snow line table.
static const uint SNOW_LINE_DAYS = 32; ///< Number of days in each month in the snow line table.
/** Structure describing the height of the snow line each day of the year
/**
* Structure describing the height of the snow line each day of the year
* @ingroup SnowLineGroup */
struct SnowLine {
byte table[SNOW_LINE_MONTHS][SNOW_LINE_DAYS]; ///< Height of the snow line each day of the year

3
src/misc/array.hpp
View File

@ -15,7 +15,8 @@
#include "fixedsizearray.hpp"
#include "str.hpp"
/** Flexible array with size limit. Implemented as fixed size
/**
* Flexible array with size limit. Implemented as fixed size
* array of fixed size arrays */
template <class T, uint B = 1024, uint N = B>
class SmallArray {

18
src/misc/blob.hpp
View File

@ -16,7 +16,8 @@
#include "../core/mem_func.hpp"
#include <new>
/** Base class for simple binary blobs.
/**
* Base class for simple binary blobs.
* Item is byte.
* The word 'simple' means:
* - no configurable allocator type (always made from heap)
@ -102,7 +103,8 @@ protected:
return (BlobHeader*)MallocT<byte>(num_bytes);
}
/** Return header pointer to the static BlobHeader with
/**
* Return header pointer to the static BlobHeader with
* both items and capacity containing zero */
static FORCEINLINE BlobHeader *Zero()
{
@ -231,7 +233,8 @@ public:
}
}
/** Reallocate if there is no free space for num_bytes bytes.
/**
* Reallocate if there is no free space for num_bytes bytes.
* @return pointer to the new data to be added */
FORCEINLINE byte *Prepare(size_t num_bytes)
{
@ -240,7 +243,8 @@ public:
return data + Length();
}
/** Increase Length() by num_bytes.
/**
* Increase Length() by num_bytes.
* @return pointer to the new data added */
FORCEINLINE byte *Append(size_t num_bytes)
{
@ -286,7 +290,8 @@ public:
}
};
/** Blob - simple dynamic T array. T (template argument) is a placeholder for any type.
/**
* Blob - simple dynamic T array. T (template argument) is a placeholder for any type.
* T can be any integral type, pointer, or structure. Using Blob instead of just plain C array
* simplifies the resource management in several ways:
* 1. When adding new item(s) it automatically grows capacity if needed.
@ -380,7 +385,8 @@ public:
return (T*)base::Append(num_items * type_size);
}
/** Ensures that given number of items can be added to the end of Blob. Returns pointer to the
/**
* Ensures that given number of items can be added to the end of Blob. Returns pointer to the
* first free (unused) item */
FORCEINLINE T *MakeFreeSpace(size_t num_items)
{

6
src/misc/countedptr.hpp
View File

@ -12,7 +12,8 @@
#ifndef COUNTEDPTR_HPP
#define COUNTEDPTR_HPP
/** CCountedPtr - simple reference counting smart pointer.
/**
* CCountedPtr - simple reference counting smart pointer.
*
* One of the standard ways how to maintain object's lifetime.
*
@ -136,7 +137,8 @@ template <class T> struct AdaptT {
};
/** Simple counted object. Use it as base of your struct/class if you want to use
/**
* Simple counted object. Use it as base of your struct/class if you want to use
* basic reference counting. Your struct/class will destroy and free itself when
* last reference to it is released (using Relese() method). The initial reference
* count (when it is created) is zero (don't forget AddRef() at least one time if

3
src/misc/dbg_helpers.cpp
View File

@ -72,7 +72,8 @@ CStrA TileStr(TileIndex tile)
return out.Transfer();
}
/** Keep track of the last assigned type_id. Used for anti-recursion.
/**
* Keep track of the last assigned type_id. Used for anti-recursion.
*static*/ size_t& DumpTarget::LastTypeId()
{
static size_t last_type_id = 0;

6
src/misc/fixedsizearray.hpp
View File

@ -14,7 +14,8 @@
#include "../core/alloc_func.hpp"
/** fixed size array
/**
* fixed size array
* Upon construction it preallocates fixed size block of memory
* for all items, but doesn't construct them. Item's construction
* is delayed. */
@ -32,7 +33,8 @@ protected:
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
/**
* the only member of fixed size array is pointer to the block
* of C array of items. Header can be found on the offset -sizeof(ArrayHeader). */
T *data;

6
src/misc/hashtable.hpp
View File

@ -106,7 +106,8 @@ struct CHashTableSlotT
}
};
/** class CHashTableT<Titem, Thash_bits> - simple hash table
/**
* class CHashTableT<Titem, Thash_bits> - simple hash table
* of pointers allocated elsewhere.
*
* Supports: Add/Find/Remove of Titems.
@ -136,7 +137,8 @@ public:
static const int Tcapacity = 1 << Thash_bits; // and num of slots 2^bits
protected:
/** each slot contains pointer to the first item in the list,
/**
* each slot contains pointer to the first item in the list,
* Titem contains pointer to the next item - GetHashNext(), SetHashNext() */
typedef CHashTableSlotT<Titem_> Slot;

12
src/misc_cmd.cpp
View File

@ -25,7 +25,8 @@
#include "table/strings.h"
/** Increase the loan of your company.
/**
* Increase the loan of your company.
* @param tile unused
* @param flags operation to perform
* @param p1 amount to increase the loan with, multitude of LOAN_INTERVAL. Only used when p2 == 2.
@ -71,7 +72,8 @@ CommandCost CmdIncreaseLoan(TileIndex tile, DoCommandFlag flags, uint32 p1, uint
return CommandCost(EXPENSES_OTHER);
}
/** Decrease the loan of your company.
/**
* Decrease the loan of your company.
* @param tile unused
* @param flags operation to perform
* @param p1 amount to decrease the loan with, multitude of LOAN_INTERVAL. Only used when p2 == 2.
@ -187,7 +189,8 @@ CommandCost CmdPause(TileIndex tile, DoCommandFlag flags, uint32 p1, uint32 p2,
return CommandCost();
}
/** Change the financial flow of your company.
/**
* Change the financial flow of your company.
* This is normally only enabled in offline mode, but if there is a debug
* build, you can cheat (to test).
* @param tile unused
@ -205,7 +208,8 @@ CommandCost CmdMoneyCheat(TileIndex tile, DoCommandFlag flags, uint32 p1, uint32
return CommandCost(EXPENSES_OTHER, -(int32)p1);
}
/** Transfer funds (money) from one company to another.
/**
* Transfer funds (money) from one company to another.
* To prevent abuse in multiplayer games you can only send money to other
* companies if you have paid off your loan (either explicitely, or implicitely
* given the fact that you have more money than loan).

9
src/misc_gui.cpp
View File

@ -899,7 +899,8 @@ struct TooltipsWindow : public Window
}
};
/** Shows a tooltip
/**
* Shows a tooltip
* @param str String to be displayed
* @param paramcount number of params to deal with
* @param params (optional) up to 5 pieces of additional information that may be added to a tooltip
@ -1410,7 +1411,8 @@ static const WindowDesc _query_string_desc(
_nested_query_string_widgets, lengthof(_nested_query_string_widgets)
);
/** Show a query popup window with a textbox in it.
/**
* Show a query popup window with a textbox in it.
* @param str StringID for the text shown in the textbox
* @param caption StringID of text shown in caption of querywindow
* @param maxsize maximum size in bytes (including terminating '\0')
@ -1564,7 +1566,8 @@ static const WindowDesc _query_desc(
_nested_query_widgets, lengthof(_nested_query_widgets)
);
/** Show a modal confirmation window with standard 'yes' and 'no' buttons
/**
* Show a modal confirmation window with standard 'yes' and 'no' buttons
* The window is aligned to the centre of its parent.
* @param caption string shown as window caption
* @param message string that will be shown for the window

3
src/music/allegro_m.cpp
View File

@ -19,7 +19,8 @@
static FMusicDriver_Allegro iFMusicDriver_Allegro;
static MIDI *_midi = NULL;
/** There are multiple modules that might be using Allegro and
/**
* There are multiple modules that might be using Allegro and
* Allegro can only be initiated once. */
extern int _allegro_instance_count;

3
src/network/core/packet.h
View File

@ -34,7 +34,8 @@ typedef uint8 PacketType; ///< Identifier for the packet
struct Packet {
/** The next packet. Used for queueing packets before sending. */
Packet *next;
/** The size of the whole packet for received packets. For packets
/**
* The size of the whole packet for received packets. For packets
* that will be sent, the value is filled in just before the
* actual transmission. */
PacketSize size;

3
src/network/network.cpp
View File

@ -471,7 +471,8 @@ static void CheckPauseOnJoin()
CheckPauseHelper(NetworkHasJoiningClient(), PM_PAUSED_JOIN);
}
/** Converts a string to ip/port/company
/**
* Converts a string to ip/port/company
* Format: IP:port#company
*
* connection_string will be re-terminated to seperate out the hostname, and company and port will

9
src/network/network_gamelist.cpp
View File

@ -27,7 +27,8 @@ NetworkGameList *_network_game_list = NULL;
static ThreadMutex *_network_game_list_mutex = ThreadMutex::New();
static NetworkGameList *_network_game_delayed_insertion_list = NULL;
/** Add a new item to the linked gamelist, but do it delayed in the next tick
/**
* Add a new item to the linked gamelist, but do it delayed in the next tick
* or so to prevent race conditions.
* @param item the item to add. Will be freed once added.
*/
@ -66,7 +67,8 @@ static void NetworkGameListHandleDelayedInsert()
_network_game_list_mutex->EndCritical();
}
/** Add a new item to the linked gamelist. If the IP and Port match
/**
* Add a new item to the linked gamelist. If the IP and Port match
* return the existing item instead of adding it again
* @param address the address of the to-be added item
* @param port the port the server is running on
@ -106,7 +108,8 @@ NetworkGameList *NetworkGameListAddItem(NetworkAddress address)
return item;
}
/** Remove an item from the gamelist linked list
/**
* Remove an item from the gamelist linked list
* @param remove pointer to the item to be removed */
void NetworkGameListRemoveItem(NetworkGameList *remove)
{

9
src/network/network_gui.cpp
View File

@ -64,7 +64,8 @@ void SortNetworkLanguages()
QSortT(_language_dropdown, NETLANG_COUNT - 1, &StringIDSorter);
}
/** Update the network new window because a new server is
/**
* Update the network new window because a new server is
* found on the network.
* @param unselect unselect the currently selected item */
void UpdateNetworkGameWindow(bool unselect)
@ -279,7 +280,8 @@ protected:
return strcasecmp((*a)->info.server_name, (*b)->info.server_name);
}
/** Sort servers by the amount of clients online on a
/**
* Sort servers by the amount of clients online on a
* server. If the two servers have the same amount, the one with the
* higher maximum is preferred. */
static int CDECL NGameClientSorter(NetworkGameList * const *a, NetworkGameList * const *b)
@ -317,7 +319,8 @@ protected:
return (r != 0) ? r : NGameDateSorter(a, b);
}
/** Sort servers by joinability. If both servers are the
/**
* Sort servers by joinability. If both servers are the
* same, prefer the non-passworded server first. */
static int CDECL NGameAllowedSorter(NetworkGameList * const *a, NetworkGameList * const *b)
{

9
src/network/network_server.cpp
View File

@ -884,7 +884,8 @@ DEF_SERVER_RECEIVE_COMMAND(PACKET_CLIENT_MAP_OK)
return SEND_COMMAND(PACKET_SERVER_ERROR)(cs, NETWORK_ERROR_NOT_EXPECTED);
}
/** The client has done a command and wants us to handle it
/**
* The client has done a command and wants us to handle it
* @param *cs the connected client that has sent the command
* @param *p the packet in which the command was sent
*/
@ -921,7 +922,8 @@ DEF_SERVER_RECEIVE_COMMAND(PACKET_CLIENT_COMMAND)
return SEND_COMMAND(PACKET_SERVER_ERROR)(cs, NETWORK_ERROR_KICKED);
}
/** Only CMD_COMPANY_CTRL is always allowed, for the rest, playas needs
/**
* Only CMD_COMPANY_CTRL is always allowed, for the rest, playas needs
* to match the company in the packet. If it doesn't, the client has done
* something pretty naughty (or a bug), and will be kicked
*/
@ -931,7 +933,8 @@ DEF_SERVER_RECEIVE_COMMAND(PACKET_CLIENT_COMMAND)
return SEND_COMMAND(PACKET_SERVER_ERROR)(cs, NETWORK_ERROR_COMPANY_MISMATCH);
}
/** @todo CMD_COMPANY_CTRL with p1 = 0 announces a new company to the server. To give the
/**
* @todo CMD_COMPANY_CTRL with p1 = 0 announces a new company to the server. To give the
* company the correct ID, the server injects p2 and executes the command. Any other p1
* is prohibited. Pretty ugly and should be redone together with its function.
* @see CmdCompanyCtrl()

18
src/newgrf.cpp
View File

@ -222,7 +222,8 @@ static std::map<GRFLocation, SpriteID> _grm_sprites;
typedef std::map<GRFLocation, byte*> GRFLineToSpriteOverride;
static GRFLineToSpriteOverride _grf_line_to_action6_sprite_override;
/** DEBUG() function dedicated to newGRF debugging messages
/**
* DEBUG() function dedicated to newGRF debugging messages
* Function is essentially the same as DEBUG(grf, severity, ...) with the
* addition of file:line information when parsing grf files.
* NOTE: for the above reason(s) grfmsg() should ONLY be used for
@ -281,7 +282,8 @@ static void ClearTemporaryNewGRFData(GRFFile *gf)
typedef std::map<StringID *, uint32> StringIDToGRFIDMapping;
static StringIDToGRFIDMapping _string_to_grf_mapping;
/** Used when setting an object's property to map to the GRF's strings
/**
* Used when setting an object's property to map to the GRF's strings
* while taking in consideration the "drift" between TTDPatch string system and OpenTTD's one
* @param grfid Id of the grf file
* @param str StringID that we want to have the equivalent in OoenTTD
@ -423,7 +425,8 @@ EngineID GetNewEngineID(const GRFFile *file, VehicleType type, uint16 internal_i
return _engine_mngr.GetID(type, internal_id, scope_grfid);
}
/** Map the colour modifiers of TTDPatch to those that Open is using.
/**
* Map the colour modifiers of TTDPatch to those that Open is using.
* @param grf_sprite pointer to the structure been modified
*/
static void MapSpriteMappingRecolour(PalSpriteID *grf_sprite)
@ -6792,7 +6795,8 @@ static void InitNewGRFFile(const GRFConfig *config, int sprite_offset)
}
/** List of what cargo labels are refittable for the given the vehicle-type.
/**
* List of what cargo labels are refittable for the given the vehicle-type.
* Only currently active labels are applied. */
static const CargoLabel _default_refitmasks_rail[] = {
'PASS', 'COAL', 'MAIL', 'LVST', 'GOOD', 'GRAI', 'WHEA', 'MAIZ', 'WOOD',
@ -6925,7 +6929,8 @@ static void FinaliseCargoArray()
}
}
/** Add all new houses to the house array. House properties can be set at any
/**
* Add all new houses to the house array. House properties can be set at any
* time in the GRF file, so we can only add a house spec to the house array
* after the file has finished loading. We also need to check the dates, due to
* the TTDPatch behaviour described below that we need to emulate. */
@ -6990,7 +6995,8 @@ static void FinaliseHouseArray()
}
}
/** Add all new industries to the industry array. Industry properties can be set at any
/**
* Add all new industries to the industry array. Industry properties can be set at any
* time in the GRF file, so we can only add a industry spec to the industry array
* after the file has finished loading. */
static void FinaliseIndustriesArray()

15
src/newgrf_callbacks.h
View File

@ -43,7 +43,8 @@ enum CallbackID {
/** Choose a sprite layout to draw, instead of the standard 0-7 range. */
CBID_STATION_SPRITE_LAYOUT = 0x14,
/** Refit capacity, the passed vehicle needs to have its ->cargo_type set to
/**
* Refit capacity, the passed vehicle needs to have its ->cargo_type set to
* the cargo we are refitting to, returns the new cargo capacity. */
CBID_VEHICLE_REFIT_CAPACITY = 0x15, // 15 bit callback
@ -86,7 +87,8 @@ enum CallbackID {
/** Called to determine if the given industry type is available */
CBID_INDUSTRY_AVAILABLE = 0x22, // 15 bit callback
/** This callback is called from vehicle purchase lists. It returns a value to be
/**
* This callback is called from vehicle purchase lists. It returns a value to be
* used as a custom string ID in the 0xD000 range. */
CBID_VEHICLE_ADDITIONAL_TEXT = 0x23,
@ -117,7 +119,8 @@ enum CallbackID {
/** Called to determine which cargoes an industry should accept. */
CBID_INDTILE_ACCEPT_CARGO = 0x2C, // 15 bit callback
/** Called to determine if a specific colour map should be used for a vehicle
/**
* Called to determine if a specific colour map should be used for a vehicle
* instead of the default livery. */
CBID_VEHICLE_COLOUR_MAPPING = 0x2D, // 15 bit callback
@ -130,7 +133,8 @@ enum CallbackID {
/** Called to determine the type (if any) of foundation to draw for industry tile. */
CBID_INDTILE_DRAW_FOUNDATIONS = 0x30, // 15 bit callback
/** Called when the company (or AI) tries to start or stop a vehicle. Mainly
/**
* Called when the company (or AI) tries to start or stop a vehicle. Mainly
* used for preventing a vehicle from leaving the depot. */
CBID_VEHICLE_START_STOP_CHECK = 0x31, // 15 bit callback, but 0xFF test is done with 8 bit
@ -146,7 +150,8 @@ enum CallbackID {
/** Called monthly on production changes, so it can be adjusted more frequently */
CBID_INDUSTRY_MONTHLYPROD_CHANGE = 0x35, // 15 bit callback
/** Called to modify various vehicle properties. Callback parameter 1
/**
* Called to modify various vehicle properties. Callback parameter 1
* specifies the property index, as used in Action 0, to change. */
CBID_VEHICLE_MODIFY_PROPERTY = 0x36, // 8/15 bit depends on queried property

6
src/newgrf_canal.h
View File

@ -16,7 +16,8 @@
#include "tile_type.h"
#include "newgrf_generic.h"
/** List of different canal 'features'.
/**
* List of different canal 'features'.
* Each feature gets an entry in the canal spritegroup table */
enum CanalFeature {
CF_WATERSLOPE,
@ -42,7 +43,8 @@ struct WaterFeature {
extern WaterFeature _water_feature[CF_END];
/** Lookup the base sprite to use for a canal.
/**
* Lookup the base sprite to use for a canal.
* @param feature Which canal feature we want.
* @param tile Tile index of canal, if appropriate.
* @return Base sprite returned by GRF, or 0 if none.

36
src/newgrf_commons.cpp
View File

@ -7,7 +7,8 @@
* 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 newgrf_commons.cpp Implementation of the class OverrideManagerBase
/**
* @file newgrf_commons.cpp Implementation of the class OverrideManagerBase
* and its descendance, present and futur
*/
@ -23,7 +24,8 @@
#include "tunnelbridge_map.h"
#include "core/mem_func.hpp"
/** Constructor of generic class
/**
* Constructor of generic class
* @param offset end of original data for this entity. i.e: houses = 110
* @param maximum of entities this manager can deal with. i.e: houses = 512
* @param invalid is the ID used to identify an invalid entity id
@ -40,7 +42,8 @@ OverrideManagerBase::OverrideManagerBase(uint16 offset, uint16 maximum, uint16 i
grfid_overrides = CallocT<uint32>(max_offset);
}
/** Destructor of the generic class.
/**
* Destructor of the generic class.
* Frees allocated memory of constructor
*/
OverrideManagerBase::~OverrideManagerBase()
@ -50,7 +53,8 @@ OverrideManagerBase::~OverrideManagerBase()
free(grfid_overrides);
}
/** Since the entity IDs defined by the GRF file does not necessarily correlate
/**
* Since the entity IDs defined by the GRF file does not necessarily correlate
* to those used by the game, the IDs used for overriding old entities must be
* translated when the entity spec is set.
* @param local_id ID in grf file
@ -81,7 +85,8 @@ void OverrideManagerBase::ResetOverride()
}
}
/** Return the ID (if ever available) of a previously inserted entity.
/**
* Return the ID (if ever available) of a previously inserted entity.
* @param grf_local_id ID of this enity withing the grfID
* @param grfid ID of the grf file
* @return the ID of the candidate, of the Invalid flag item ID
@ -100,7 +105,8 @@ uint16 OverrideManagerBase::GetID(uint8 grf_local_id, uint32 grfid)
return invalid_ID;
}
/** Reserves a place in the mapping array for an entity to be installed
/**
* Reserves a place in the mapping array for an entity to be installed
* @param grf_local_id is an arbitrary id given by the grf's author. Also known as setid
* @param grfid is the id of the grf file itself
* @param substitute_id is the original entity from which data is copied for the new one
@ -134,7 +140,8 @@ uint16 OverrideManagerBase::AddEntityID(byte grf_local_id, uint32 grfid, byte su
return invalid_ID;
}
/** Gives the substitute of the entity, as specified by the grf file
/**
* Gives the substitute of the entity, as specified by the grf file
* @param entity_id of the entity being queried
* @return mapped id
*/
@ -143,7 +150,8 @@ uint16 OverrideManagerBase::GetSubstituteID(uint16 entity_id)
return mapping_ID[entity_id].substitute_id;
}
/** Install the specs into the HouseSpecs array
/**
* Install the specs into the HouseSpecs array
* It will find itself the proper slot onwhich it will go
* @param hs HouseSpec read from the grf file, ready for inclusion
*/
@ -170,7 +178,8 @@ void HouseOverrideManager::SetEntitySpec(const HouseSpec *hs)
}
}
/** Return the ID (if ever available) of a previously inserted entity.
/**
* Return the ID (if ever available) of a previously inserted entity.
* @param grf_local_id ID of this enity withing the grfID
* @param grfid ID of the grf file
* @return the ID of the candidate, of the Invalid flag item ID
@ -188,7 +197,8 @@ uint16 IndustryOverrideManager::GetID(uint8 grf_local_id, uint32 grfid)
return invalid_ID;
}
/** Method to find an entity ID and to mark it as reserved for the Industry to be included.
/**
* Method to find an entity ID and to mark it as reserved for the Industry to be included.
* @param grf_local_id ID used by the grf file for pre-installation work (equivalent of TTDPatch's setid
* @param grfid ID of the current grf file
* @param substitute_id industry from which data has been copied
@ -223,7 +233,8 @@ uint16 IndustryOverrideManager::AddEntityID(byte grf_local_id, uint32 grfid, byt
return invalid_ID;
}
/** Method to install the new indistry data in its proper slot
/**
* Method to install the new indistry data in its proper slot
* The slot assigment is internal of this method, since it requires
* checking what is available
* @param inds Industryspec that comes from the grf decoding process
@ -277,7 +288,8 @@ void IndustryTileOverrideManager::SetEntitySpec(const IndustryTileSpec *its)
}
}
/** Function used by houses (and soon industries) to get information
/**
* Function used by houses (and soon industries) to get information
* on type of "terrain" the tile it is queries sits on.
* @param tile TileIndex of the tile been queried
* @param upper_halftile If true, query upper halftile in case of rail tiles.

3
src/newgrf_commons.h
View File

@ -7,7 +7,8 @@
* 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 newgrf_commons.h This file simplyfies and embeds a common mechanism of
/**
* @file newgrf_commons.h This file simplyfies and embeds a common mechanism of
* loading/saving and mapping of grf entities.
*/

24
src/newgrf_config.cpp
View File

@ -240,7 +240,8 @@ void UpdateNewGRFConfigPalette()
for (GRFConfig *c = _grfconfig_static; c != NULL; c = c->next) c->SetSuitablePalette();
}
/** Calculate the MD5 sum for a GRF, and store it in the config.
/**
* Calculate the MD5 sum for a GRF, and store it in the config.
* @param config GRF to compute.
* @return MD5 sum was successfully computed
*/
@ -268,7 +269,8 @@ static bool CalcGRFMD5Sum(GRFConfig *config)
}
/** Find the GRFID of a given grf, and calculate its md5sum.
/**
* Find the GRFID of a given grf, and calculate its md5sum.
* @param config grf to fill.
* @param is_static grf is static.
* @return Operation was successfully completed.
@ -300,7 +302,8 @@ bool FillGRFDetails(GRFConfig *config, bool is_static)
}
/** Clear a GRF Config list, freeing all nodes.
/**
* Clear a GRF Config list, freeing all nodes.
* @param config Start of the list.
* @post \a config is set to \c NULL.
*/
@ -315,7 +318,8 @@ void ClearGRFConfigList(GRFConfig **config)
}
/** Copy a GRF Config list
/**
* Copy a GRF Config list
* @param dst pointer to destination list
* @param src pointer to source list values
* @param init_only the copied GRF will be processed up to GLS_INIT
@ -381,7 +385,8 @@ void AppendStaticGRFConfigs(GRFConfig **dst)
RemoveDuplicatesFromGRFConfigList(*dst);
}
/** Appends an element to a list of GRFs
/**
* Appends an element to a list of GRFs
* @param dst the head of the list to add to
* @param el the new tail to be */
void AppendToGRFConfigList(GRFConfig **dst, GRFConfig *el)
@ -402,7 +407,8 @@ void ResetGRFConfig(bool defaults)
}
/** Check if all GRFs in the GRF config from a savegame can be loaded.
/**
* Check if all GRFs in the GRF config from a savegame can be loaded.
* @param grfconfig GrfConfig to check
* @return will return any of the following 3 values:<br>
* <ul>
@ -573,7 +579,8 @@ void ScanNewGRFFiles()
}
/** Find a NewGRF in the scanned list.
/**
* Find a NewGRF in the scanned list.
* @param grfid GRFID to look for,
* @param md5sum Expected MD5 sum (set to \c NULL if not relevant).
* @return The matching grf, if it exists in #_all_grfs, else \c NULL.
@ -641,7 +648,8 @@ char *FindUnknownGRFName(uint32 grfid, uint8 *md5sum, bool create)
#endif /* ENABLE_NETWORK */
/** Retrieve a NewGRF from the current config by its grfid.
/**
* Retrieve a NewGRF from the current config by its grfid.
* @param grfid grf to look for.
* @param mask GRFID mask to allow for partial matching.
* @return The grf config, if it exists, else \c NULL.

3
src/newgrf_config.h
View File

@ -73,7 +73,8 @@ struct GRFIdentifier {
uint32 grfid; ///< GRF ID (defined by Action 0x08)
uint8 md5sum[16]; ///< MD5 checksum of file to distinguish files with the same GRF ID (eg. newer version of GRF)
/** Does the identification match the provided values?
/**
* Does the identification match the provided values?
* @param grfid Expected grfid.
* @param md5sum Expected md5sum, may be \c NULL (in which case, do not check it).
* @return the object has the provided grfid and md5sum.

3
src/newgrf_engine.cpp
View File

@ -881,7 +881,8 @@ static inline void NewVehicleResolver(ResolverObject *res, EngineID engine_type,
}
/** Retrieve the SpriteGroup for the specified vehicle.
/**
* Retrieve the SpriteGroup for the specified vehicle.
* If the vehicle is not specified, the purchase list group for the engine is
* chosen. For trains, an additional engine override lookup is performed.
* @param engine Engine type of the vehicle.

3
src/newgrf_generic.cpp
View File

@ -134,7 +134,8 @@ static inline void NewGenericResolver(ResolverObject *res, const GRFFile *grffil
}
/** Follow a generic feature callback list and return the first successful
/**
* Follow a generic feature callback list and return the first successful
* answer
* @param feature GRF Feature of callback
* @param object pre-populated resolver object

15
src/newgrf_gui.cpp
View File

@ -554,7 +554,8 @@ struct NewGRFWindow : public QueryStringBaseWindow {
this->DrawEditBox(SNGRFS_FILTER);
}
/** Pick the palette for the sprite of the grf to display.
/**
* Pick the palette for the sprite of the grf to display.
* @param c grf to display.
* @return Palette for the sprite.
*/
@ -923,7 +924,8 @@ struct NewGRFWindow : public QueryStringBaseWindow {
this->InvalidateData();
}
/** Calback to update internal data.
/**
* Calback to update internal data.
* - 0: (optionally) build availables, update button status.
* - 1: build availables, Add newly found grfs, update button status.
* - 2: (optionally) build availables, Reset preset, + 3
@ -1160,7 +1162,8 @@ NewGRFWindow::GUIGRFConfigList::FilterFunction * const NewGRFWindow::filter_func
&TagNameFilter,
};
/** Custom nested widget container for the NewGRF gui.
/**
* Custom nested widget container for the NewGRF gui.
* Depending on the space in the gui, it uses either
* - two column mode, put the #acs and the #avs underneath each other and the #info next to it, or
* - three column mode, put the #avs, #acs, and #info each in its own column.
@ -1491,7 +1494,8 @@ static const WindowDesc _newgrf_desc(
_nested_newgrf_widgets, lengthof(_nested_newgrf_widgets)
);
/** Callback function for the newgrf 'apply changes' confirmation window
/**
* Callback function for the newgrf 'apply changes' confirmation window
* @param w Window which is calling this callback
* @param confirmed boolean value, true when yes was clicked, false otherwise
*/
@ -1521,7 +1525,8 @@ static void NewGRFConfirmationCallback(Window *w, bool confirmed)
/** Setup the NewGRF gui
/**
* Setup the NewGRF gui
* @param editable allow the user to make changes to the grfconfig in the window
* @param show_params show information about what parameters are set for the grf files
* @param exec_changes if changes are made to the list (editable is true), apply these

12
src/newgrf_house.cpp
View File

@ -146,7 +146,8 @@ typedef struct {
TileIndex north_tile; ///< Northern tile of the house.
} SearchNearbyHouseData;
/** Callback function to search a house by its HouseID
/**
* Callback function to search a house by its HouseID
* @param tile TileIndex to be examined
* @param user_data SearchNearbyHouseData
* @return true or false, if found or not
@ -169,7 +170,8 @@ static bool SearchNearbyHouseID(TileIndex tile, void *user_data)
return false;
}
/** Callback function to search a house by its classID
/**
* Callback function to search a house by its classID
* @param tile TileIndex to be examined
* @param user_data SearchNearbyHouseData
* @return true or false, if found or not
@ -192,7 +194,8 @@ static bool SearchNearbyHouseClass(TileIndex tile, void *user_data)
return false;
}
/** Callback function to search a house by its grfID
/**
* Callback function to search a house by its grfID
* @param tile TileIndex to be examined
* @param user_data SearchNearbyHouseData
* @return true or false, if found or not
@ -214,7 +217,8 @@ static bool SearchNearbyHouseGRFID(TileIndex tile, void *user_data)
return false;
}
/** This function will activate a search around a central tile, looking for some houses
/**
* This function will activate a search around a central tile, looking for some houses
* that fit the requested characteristics
* @param parameter that is given by the callback.
* bits 0..6 radius of the search

9
src/newgrf_industries.cpp
View File

@ -100,7 +100,8 @@ static uint32 GetClosestIndustry(TileIndex tile, IndustryType type, const Indust
return best_dist;
}
/** Implementation of both var 67 and 68
/**
* Implementation of both var 67 and 68
* since the mechanism is almost the same, it is easier to regroup them on the same
* function.
* @param param_setID parameter given to the callback, which is the set id, or the local id, in our terminology
@ -154,7 +155,8 @@ static uint32 GetCountAndDistanceOfClosestInstance(byte param_setID, byte layout
return count << 16 | GB(closest_dist, 0, 16);
}
/** This function implements the industries variables that newGRF defines.
/**
* This function implements the industries variables that newGRF defines.
* @param object the object that we want to query
* @param variable that is queried
* @param parameter unused
@ -447,7 +449,8 @@ uint32 IndustryLocationGetVariable(const ResolverObject *object, byte variable,
return IndustryGetVariable(object, variable, parameter, available);
}
/** Check that the industry callback allows creation of the industry.
/**
* Check that the industry callback allows creation of the industry.
* @param tile %Tile to build the industry.
* @param type Type of industry to build.
* @param layout Layout number.

6
src/newgrf_industrytiles.cpp
View File

@ -45,7 +45,8 @@ uint32 GetNearbyIndustryTileInformation(byte parameter, TileIndex tile, Industry
return GetNearbyTileInformation(tile) | (is_same_industry ? 1 : 0) << 8;
}
/** This is the position of the tile relative to the northernmost tile of the industry.
/**
* This is the position of the tile relative to the northernmost tile of the industry.
* Format: 00yxYYXX
* Variable Content
* x the x offset from the northernmost tile
@ -250,7 +251,8 @@ bool DrawNewIndustryTile(TileInfo *ti, Industry *i, IndustryGfx gfx, const Indus
extern bool IsSlopeRefused(Slope current, Slope refused);
/** Check the slope of a tile of a new industry.
/**
* Check the slope of a tile of a new industry.
* @param ind_base_tile Base tile of the industry.
* @param ind_tile Tile to check.
* @param its Tile specification.

6
src/newgrf_station.cpp
View File

@ -821,7 +821,8 @@ int AllocateSpecToStation(const StationSpec *statspec, BaseStation *st, bool exe
}
/** Deallocate a StationSpec from a Station. Called when removing a single station tile.
/**
* Deallocate a StationSpec from a Station. Called when removing a single station tile.
* @param st Station to work with.
* @param specindex Index of the custom station within the Station's spec list.
* @return Indicates whether the StationSpec was deallocated.
@ -862,7 +863,8 @@ void DeallocateSpecFromStation(BaseStation *st, byte specindex)
StationUpdateAnimTriggers(st);
}
/** Draw representation of a station tile for GUI purposes.
/**
* Draw representation of a station tile for GUI purposes.
* @param x Position x of image.
* @param y Position y of image.
* @param axis Axis.

6
src/newgrf_station.h
View File

@ -64,7 +64,8 @@ struct StationSpec {
*/
byte disallowed_lengths;
/** Number of tile layouts.
/**
* Number of tile layouts.
* A minimum of 8 is required is required for stations.
* 0-1 = plain platform
* 2-3 = platform with building
@ -75,7 +76,8 @@ struct StationSpec {
DrawTileSprites *renderdata; ///< Array of tile layouts.
bool copied_renderdata;
/** Cargo threshold for choosing between little and lots of cargo
/**
* Cargo threshold for choosing between little and lots of cargo
* @note little/lots are equivalent to the moving/loading states for vehicles
*/
uint16 cargo_threshold;

3
src/newgrf_text.cpp
View File

@ -7,7 +7,8 @@
* 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 newgrf_text.cpp
/**
* @file newgrf_text.cpp
* Implementation of Action 04 "universal holder" structure and functions.
* This file implements a linked-lists of strings,
* holding everything that the newgrf action 04 will send over to OpenTTD.

3
src/newgrf_town.cpp
View File

@ -13,7 +13,8 @@
#include "debug.h"
#include "town.h"
/** This function implements the town variables that newGRF defines.
/**
* This function implements the town variables that newGRF defines.
* @param variable that is queried
* @param parameter unused
* @param available will return false if ever the variable asked for does not exist

3
src/newgrf_townname.cpp
View File

@ -7,7 +7,8 @@
* 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 newgrf_townname.cpp
/**
* @file newgrf_townname.cpp
* Implementation of Action 0F "universal holder" structure and functions.
* This file implements a linked-lists of townname generators,
* holding everything that the newgrf action 0F will send over to OpenTTD.

3
src/newgrf_townname.h
View File

@ -7,7 +7,8 @@
* 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 newgrf_townname.h
/**
* @file newgrf_townname.h
* Header of Action 0F "universal holder" structure and functions
*/

9
src/news_gui.cpp
View File

@ -41,7 +41,8 @@ static uint _total_news = 0; ///< current number of news items
static NewsItem *_oldest_news = NULL; ///< head of news items queue
static NewsItem *_latest_news = NULL; ///< tail of news items queue
/** Forced news item.
/**
* Forced news item.
* Users can force an item by accessing the history or "last message".
* If the message being shown was forced by the user, a pointer is stored
* in _forced_news. Otherwise, \a _forced_news variable is NULL. */
@ -766,7 +767,8 @@ void DeleteVehicleNews(VehicleID vid, StringID news)
}
}
/** Remove news regarding given station so there are no 'unknown station now accepts Mail'
/**
* Remove news regarding given station so there are no 'unknown station now accepts Mail'
* or 'First train arrived at unknown station' news items.
* @param sid station to remove news about
*/
@ -783,7 +785,8 @@ void DeleteStationNews(StationID sid)
}
}
/** Remove news regarding given industry
/**
* Remove news regarding given industry
* @param iid industry to remove news about
*/
void DeleteIndustryNews(IndustryID iid)

6
src/openttd.cpp
View File

@ -316,7 +316,8 @@ static void InitializeDynamicVariables()
}
/** Unitializes drivers, frees allocated memory, cleans pools, ...
/**
* Unitializes drivers, frees allocated memory, cleans pools, ...
* Generally, prepares the game for shutting down
*/
static void ShutdownGame()
@ -1273,7 +1274,8 @@ void StateGameLoop()
assert(IsLocalCompany());
}
/** Create an autosave. The default name is "autosave#.sav". However with
/**
* Create an autosave. The default name is "autosave#.sav". However with
* the setting 'keep_all_autosave' the name defaults to company-name + date */
static void DoAutosave()
{

6
src/order_base.h
View File

@ -254,7 +254,8 @@ public:
void ConvertFromOldSavegame();
};
/** Shared order list linking together the linked list of orders and the list
/**
* Shared order list linking together the linked list of orders and the list
* of vehicles sharing this order list.
*/
struct OrderList : OrderListPool::PoolItem<&_orderlist_pool> {
@ -275,7 +276,8 @@ public:
: first(NULL), num_orders(num_orders), num_vehicles(0), first_shared(NULL),
timetable_duration(0) { }
/** Create an order list with the given order chain for the given vehicle.
/**
* Create an order list with the given order chain for the given vehicle.
* @param chain pointer to the first order of the order chain
* @param v any vehicle using this orderlist
*/

24
src/order_cmd.cpp
View File

@ -450,7 +450,8 @@ static uint GetOrderDistance(const Order *prev, const Order *cur, const Vehicle
return DistanceManhattan(prev_tile, cur_tile);
}
/** Add an order to the orderlist of a vehicle.
/**
* Add an order to the orderlist of a vehicle.
* @param tile unused
* @param flags operation to perform
* @param p1 various bitstuffed elements
@ -718,7 +719,8 @@ CommandCost CmdInsertOrder(TileIndex tile, DoCommandFlag flags, uint32 p1, uint3
return CommandCost();
}
/** Declone an order-list
/**
* Declone an order-list
* @param *dst delete the orders of this vehicle
* @param flags execution flags
*/
@ -732,7 +734,8 @@ static CommandCost DecloneOrder(Vehicle *dst, DoCommandFlag flags)
return CommandCost();
}
/** Delete an order from the orderlist of a vehicle.
/**
* Delete an order from the orderlist of a vehicle.
* @param tile unused
* @param flags operation to perform
* @param p1 the ID of the vehicle
@ -800,7 +803,8 @@ CommandCost CmdDeleteOrder(TileIndex tile, DoCommandFlag flags, uint32 p1, uint3
return CommandCost();
}
/** Goto order of order-list.
/**
* Goto order of order-list.
* @param tile unused
* @param flags operation to perform
* @param p1 The ID of the vehicle which order is skipped
@ -914,7 +918,8 @@ CommandCost CmdMoveOrder(TileIndex tile, DoCommandFlag flags, uint32 p1, uint32
return CommandCost();
}
/** Modify an order in the orderlist of a vehicle.
/**
* Modify an order in the orderlist of a vehicle.
* @param tile unused
* @param flags operation to perform
* @param p1 various bitstuffed elements
@ -1150,7 +1155,8 @@ CommandCost CmdModifyOrder(TileIndex tile, DoCommandFlag flags, uint32 p1, uint3
return CommandCost();
}
/** Clone/share/copy an order-list of another vehicle.
/**
* Clone/share/copy an order-list of another vehicle.
* @param tile unused
* @param flags operation to perform
* @param p1 various bitstuffed elements
@ -1278,7 +1284,8 @@ CommandCost CmdCloneOrder(TileIndex tile, DoCommandFlag flags, uint32 p1, uint32
return CommandCost();
}
/** Add/remove refit orders from an order
/**
* Add/remove refit orders from an order
* @param tile Not used
* @param flags operation to perform
* @param p1 VehicleIndex of the vehicle having the order
@ -1431,7 +1438,8 @@ void RestoreVehicleOrders(const Vehicle *v, const BackuppedOrders *bak)
DoCommandP(0, bak->group, v->index, CMD_ADD_VEHICLE_GROUP);
}
/** Restore the current order-index of a vehicle and sets service-interval.
/**
* Restore the current order-index of a vehicle and sets service-interval.
* @param tile unused
* @param flags operation to perform
* @param p1 the ID of the vehicle

3
src/order_gui.cpp
View File

@ -391,7 +391,8 @@ static Order GetOrderCmdFromTile(const Vehicle *v, TileIndex tile)
return order;
}
/** %Order window code for all vehicles.
/**
* %Order window code for all vehicles.
*
* At the bottom of the window two button rows are located for changing the orders of the vehicle.
*

9
src/os/unix/unix.cpp
View File

@ -126,7 +126,8 @@ const char *GetCurrentLocale(const char *param);
#define INTERNALCODE "UTF-8"
/** Try and try to decipher the current locale from environmental
/**
* Try and try to decipher the current locale from environmental
* variables. MacOSX is hardcoded, other OS's are dynamic. If no suitable
* locale can be found, don't do any conversion "" */
static const char *GetLocalCode()
@ -174,7 +175,8 @@ static const char *convert_tofrom_fs(iconv_t convd, const char *name)
return buf;
}
/** Convert from OpenTTD's encoding to that of the local environment
/**
* Convert from OpenTTD's encoding to that of the local environment
* @param name pointer to a valid string that will be converted
* @return pointer to a new stringbuffer that contains the converted string */
const char *OTTD2FS(const char *name)
@ -193,7 +195,8 @@ const char *OTTD2FS(const char *name)
return convert_tofrom_fs(convd, name);
}
/** Convert to OpenTTD's encoding from that of the local environment
/**
* Convert to OpenTTD's encoding from that of the local environment
* @param name pointer to a valid string that will be converted
* @return pointer to a new stringbuffer that contains the converted string */
const char *FS2OTTD(const char *name)

12
src/os/windows/win32.cpp
View File

@ -41,7 +41,8 @@ bool MyShowCursor(bool show)
return !show;
}
/** Helper function needed by dynamically loading libraries
/**
* Helper function needed by dynamically loading libraries
* XXX: Hurray for MS only having an ANSI GetProcAddress function
* on normal windows and no Wide version except for in Windows Mobile/CE */
bool LoadLibraryList(Function proc[], const char *dll)
@ -631,7 +632,8 @@ const TCHAR *OTTD2FS(const char *name)
}
/** Convert to OpenTTD's encoding from that of the environment in
/**
* Convert to OpenTTD's encoding from that of the environment in
* UNICODE. OpenTTD encoding is UTF8, local is wide
* @param name pointer to a valid string that will be converted
* @param utf8_buf pointer to a valid buffer that will receive the converted string
@ -649,7 +651,8 @@ char *convert_from_fs(const wchar_t *name, char *utf8_buf, size_t buflen)
}
/** Convert from OpenTTD's encoding to that of the environment in
/**
* Convert from OpenTTD's encoding to that of the environment in
* UNICODE. OpenTTD encoding is UTF8, local is wide
* @param name pointer to a valid string that will be converted
* @param utf16_buf pointer to a valid wide-char buffer that will receive the
@ -667,7 +670,8 @@ wchar_t *convert_to_fs(const char *name, wchar_t *utf16_buf, size_t buflen)
return utf16_buf;
}
/** Our very own SHGetFolderPath function for support of windows operating
/**
* Our very own SHGetFolderPath function for support of windows operating
* systems that don't have this function (eg Win9x, etc.). We try using the
* native function, and if that doesn't exist we will try a more crude approach
* of environment variables and hope for the best */

6
src/pathfinder/follow_track.hpp
View File

@ -21,7 +21,8 @@
#include "../depot_map.h"
#include "pf_performance_timer.hpp"
/** Track follower helper template class (can serve pathfinders and vehicle
/**
* Track follower helper template class (can serve pathfinders and vehicle
* controllers). See 6 different typedefs below for 3 different transport
* types w/ or w/o 90-deg turns allowed */
template <TransportType Ttr_type_, typename VehicleType, bool T90deg_turns_allowed_ = true, bool Tmask_reserved_tracks = false>
@ -110,7 +111,8 @@ struct CFollowTrackT
return INVALID_DIAGDIR;
}
/** main follower routine. Fills all members and return true on success.
/**
* main follower routine. Fills all members and return true on success.
* Otherwise returns false if track can't be followed. */
inline bool Follow(TileIndex old_tile, Trackdir old_td)
{

3
src/pathfinder/npf/aystar.h
View File

@ -7,7 +7,8 @@
* 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 aystar.h
/**
* @file aystar.h
* This file has the header for AyStar
* AyStar is a fast pathfinding routine and is used for things like
* AI_pathfinding and Train_pathfinding.

3
src/pathfinder/npf/queue.cpp
View File

@ -435,7 +435,8 @@ void clear_Hash(Hash *h, bool free_values)
h->size = 0;
}
/** Finds the node that that saves this key pair. If it is not
/**
* Finds the node that that saves this key pair. If it is not
* found, returns NULL. If it is found, *prev is set to the
* node before the one found, or if the node found was the first in the bucket
* to NULL. If it is not found, *prev is set to the last HashNode in the

15
src/pathfinder/npf/queue.h
View File

@ -98,7 +98,8 @@ void init_InsSort(Queue *q);
/* The amount of elements that will be malloc'd at a time */
#define BINARY_HEAP_BLOCKSIZE_BITS 10
/** Initializes a binary heap and allocates internal memory for maximum of
/**
* Initializes a binary heap and allocates internal memory for maximum of
* max_size elements */
void init_BinaryHeap(Queue *q, uint max_size);
@ -133,20 +134,24 @@ struct Hash {
/* Call these function to manipulate a hash */
/** Deletes the value with the specified key pair from the hash and returns
/**
* Deletes the value with the specified key pair from the hash and returns
* that value. Returns NULL when the value was not present. The value returned
* is _not_ free()'d! */
void *Hash_Delete(Hash *h, uint key1, uint key2);
/** Sets the value associated with the given key pair to the given value.
/**
* Sets the value associated with the given key pair to the given value.
* Returns the old value if the value was replaced, NULL when it was not yet present. */
void *Hash_Set(Hash *h, uint key1, uint key2, void *value);
/** Gets the value associated with the given key pair, or NULL when it is not
/**
* Gets the value associated with the given key pair, or NULL when it is not
* present. */
void *Hash_Get(const Hash *h, uint key1, uint key2);
/* Call these function to create/destroy a hash */
/** Builds a new hash in an existing struct. Make sure that hash() always
/**
* Builds a new hash in an existing struct. Make sure that hash() always
* returns a hash less than num_buckets! Call delete_hash after use */
void init_Hash(Hash *h, Hash_HashProc *hash, uint num_buckets);
/**

3
src/pathfinder/opf/opf_ship.cpp
View File

@ -178,7 +178,8 @@ bad:;
return best_bird_dist;
}
/** returns the track to choose on the next tile, or -1 when it's better to
/**
* returns the track to choose on the next tile, or -1 when it's better to
* reverse. The tile given is the tile we are about to enter, enterdir is the
* direction in which we are entering the tile */
Track OPFShipChooseTrack(const Ship *v, TileIndex tile, DiagDirection enterdir, TrackBits tracks)

3
src/pathfinder/yapf/nodelist.hpp
View File

@ -16,7 +16,8 @@
#include "../../misc/hashtable.hpp"
#include "../../misc/binaryheap.hpp"
/** Hash table based node list multi-container class.
/**
* Hash table based node list multi-container class.
* Implements open list, closed list and priority queue for A-star
* path finder. */
template <class Titem_, int Thash_bits_open_, int Thash_bits_closed_>

15
src/pathfinder/yapf/yapf_base.hpp
View File

@ -17,7 +17,8 @@
extern int _total_pf_time_us;
/** CYapfBaseT - A-star type path finder base class.
/**
* CYapfBaseT - A-star type path finder base class.
* Derive your own pathfinder from it. You must provide the following template argument:
* Types - used as collection of local types used in pathfinder
*
@ -108,7 +109,8 @@ public:
return *m_settings;
}
/** Main pathfinder routine:
/**
* Main pathfinder routine:
* - set startup node(s)
* - main loop that stops if:
* - the destination was found
@ -174,7 +176,8 @@ public:
return bDestFound;
}
/** If path was found return the best node that has reached the destination. Otherwise
/**
* If path was found return the best node that has reached the destination. Otherwise
* return the best visited node (which was nearest to the destination).
*/
FORCEINLINE Node *GetBestNode()
@ -182,7 +185,8 @@ public:
return (m_pBestDestNode != NULL) ? m_pBestDestNode : m_pBestIntermediateNode;
}
/** Calls NodeList::CreateNewNode() - allocates new node that can be filled and used
/**
* Calls NodeList::CreateNewNode() - allocates new node that can be filled and used
* as argument for AddStartupNode() or AddNewNode()
*/
FORCEINLINE Node& CreateNewNode()
@ -217,7 +221,8 @@ public:
}
}
/** AddNewNode() - called by Tderived::PfFollowNode() for each child node.
/**
* AddNewNode() - called by Tderived::PfFollowNode() for each child node.
* Nodes are evaluated here and added into open list */
void AddNewNode(Node &n, const TrackFollower &tf)
{

6
src/pathfinder/yapf/yapf_common.hpp
View File

@ -146,7 +146,8 @@ public:
return bDest;
}
/** Called by YAPF to calculate cost estimate. Calculates distance to the destination
/**
* Called by YAPF to calculate cost estimate. Calculates distance to the destination
* adds it to the actual cost from origin and stores the sum to the Node::m_estimate */
inline bool PfCalcEstimate(Node& n)
{
@ -174,7 +175,8 @@ public:
}
};
/** YAPF template that uses Ttypes template argument to determine all YAPF
/**
* YAPF template that uses Ttypes template argument to determine all YAPF
* components (base classes) from which the actual YAPF is composed.
* For example classes consult: CYapfRail_TypesT template and its instantiations:
* CYapfRail1, CYapfRail2, CYapfRail3, CYapfAnyDepotRail1, CYapfAnyDepotRail2, CYapfAnyDepotRail3 */

33
src/pathfinder/yapf/yapf_costcache.hpp
View File

@ -14,7 +14,8 @@
#include "../../date_func.h"
/** CYapfSegmentCostCacheNoneT - the formal only yapf cost cache provider that implements
/**
* CYapfSegmentCostCacheNoneT - the formal only yapf cost cache provider that implements
* PfNodeCacheFetch() and PfNodeCacheFlush() callbacks. Used when nodes don't have CachedData
* defined (they don't count with any segment cost caching).
*/
@ -25,14 +26,16 @@ public:
typedef typename Types::Tpf Tpf; ///< the pathfinder class (derived from THIS class)
typedef typename Types::NodeList::Titem Node; ///< this will be our node type
/** Called by YAPF to attach cached or local segment cost data to the given node.
/**
* Called by YAPF to attach cached or local segment cost data to the given node.
* @return true if globally cached data were used or false if local data was used */
FORCEINLINE bool PfNodeCacheFetch(Node& n)
{
return false;
}
/** Called by YAPF to flush the cached segment cost data back into cache storage.
/**
* Called by YAPF to flush the cached segment cost data back into cache storage.
* Current cache implementation doesn't use that. */
FORCEINLINE void PfNodeCacheFlush(Node& n)
{
@ -40,7 +43,8 @@ public:
};
/** CYapfSegmentCostCacheLocalT - the yapf cost cache provider that implements fake segment
/**
* CYapfSegmentCostCacheLocalT - the yapf cost cache provider that implements fake segment
* cost caching functionality for yapf. Used when node needs caching, but you don't want to
* cache the segment costs.
*/
@ -65,7 +69,8 @@ protected:
}
public:
/** Called by YAPF to attach cached or local segment cost data to the given node.
/**
* Called by YAPF to attach cached or local segment cost data to the given node.
* @return true if globally cached data were used or false if local data was used */
FORCEINLINE bool PfNodeCacheFetch(Node& n)
{
@ -74,7 +79,8 @@ public:
return false;
}
/** Called by YAPF to flush the cached segment cost data back into cache storage.
/**
* Called by YAPF to flush the cached segment cost data back into cache storage.
* Current cache implementation doesn't use that. */
FORCEINLINE void PfNodeCacheFlush(Node& n)
{
@ -82,7 +88,8 @@ public:
};
/** Base class for segment cost cache providers. Contains global counter
/**
* Base class for segment cost cache providers. Contains global counter
* of track layout changes and static notification function called whenever
* the track layout changes. It is implemented as base class because it needs
* to be shared between all rail YAPF types (one shared counter, one notification
@ -98,7 +105,8 @@ struct CSegmentCostCacheBase
};
/** CSegmentCostCacheT - template class providing hash-map and storage (heap)
/**
* CSegmentCostCacheT - template class providing hash-map and storage (heap)
* of Tsegment structures. Each rail node contains pointer to the segment
* that contains cached (or non-cached) segment cost information. Nodes can
* differ by key type, but they use the same segment type. Segment key should
@ -142,7 +150,8 @@ struct CSegmentCostCacheT
}
};
/** CYapfSegmentCostCacheGlobalT - the yapf cost cache provider that adds the segment cost
/**
* CYapfSegmentCostCacheGlobalT - the yapf cost cache provider that adds the segment cost
* caching functionality to yapf. Using this class as base of your will provide the global
* segment cost caching services for your Nodes.
*/
@ -192,7 +201,8 @@ protected:
}
public:
/** Called by YAPF to attach cached or local segment cost data to the given node.
/**
* Called by YAPF to attach cached or local segment cost data to the given node.
* @return true if globally cached data were used or false if local data was used */
FORCEINLINE bool PfNodeCacheFetch(Node& n)
{
@ -206,7 +216,8 @@ public:
return found;
}
/** Called by YAPF to flush the cached segment cost data back into cache storage.
/**
* Called by YAPF to flush the cached segment cost data back into cache storage.
* Current cache implementation doesn't use that. */
FORCEINLINE void PfNodeCacheFlush(Node& n)
{

3
src/pathfinder/yapf/yapf_costrail.hpp
View File

@ -276,7 +276,8 @@ public:
m_max_cost = max_cost;
}
/** Called by YAPF to calculate the cost from the origin to the given node.
/**
* Called by YAPF to calculate the cost from the origin to the given node.
* Calculates only the cost of given node, adds it to the parent node cost
* and stores the result into Node::m_cost member */
FORCEINLINE bool PfCalcCost(Node &n, const TrackFollower *tf)

9
src/pathfinder/yapf/yapf_destrail.hpp
View File

@ -63,7 +63,8 @@ public:
return bDest;
}
/** Called by YAPF to calculate cost estimate. Calculates distance to the destination
/**
* Called by YAPF to calculate cost estimate. Calculates distance to the destination
* adds it to the actual cost from origin and stores the sum to the Node::m_estimate */
FORCEINLINE bool PfCalcEstimate(Node& n)
{
@ -102,7 +103,8 @@ public:
IsWaitingPositionFree(Yapf().GetVehicle(), tile, td, !TrackFollower::Allow90degTurns());
}
/** Called by YAPF to calculate cost estimate. Calculates distance to the destination
/**
* Called by YAPF to calculate cost estimate. Calculates distance to the destination
* adds it to the actual cost from origin and stores the sum to the Node::m_estimate. */
FORCEINLINE bool PfCalcEstimate(Node& n)
{
@ -181,7 +183,8 @@ public:
return bDest;
}
/** Called by YAPF to calculate cost estimate. Calculates distance to the destination
/**
* Called by YAPF to calculate cost estimate. Calculates distance to the destination
* adds it to the actual cost from origin and stores the sum to the Node::m_estimate */
FORCEINLINE bool PfCalcEstimate(Node& n)
{

9
src/pathfinder/yapf/yapf_rail.cpp
View File

@ -201,7 +201,8 @@ protected:
}
public:
/** Called by YAPF to move from the given node to the next tile. For each
/**
* Called by YAPF to move from the given node to the next tile. For each
* reachable trackdir on the new tile creates new node, initializes it
* and adds it to the open list by calling Yapf().AddNewNode(n) */
inline void PfFollowNode(Node& old_node)
@ -295,7 +296,8 @@ protected:
}
public:
/** Called by YAPF to move from the given node to the next tile. For each
/**
* Called by YAPF to move from the given node to the next tile. For each
* reachable trackdir on the new tile creates new node, initializes it
* and adds it to the open list by calling Yapf().AddNewNode(n) */
inline void PfFollowNode(Node& old_node)
@ -376,7 +378,8 @@ protected:
}
public:
/** Called by YAPF to move from the given node to the next tile. For each
/**
* Called by YAPF to move from the given node to the next tile. For each
* reachable trackdir on the new tile creates new node, initializes it
* and adds it to the open list by calling Yapf().AddNewNode(n) */
inline void PfFollowNode(Node& old_node)

12
src/pathfinder/yapf/yapf_road.cpp
View File

@ -95,7 +95,8 @@ protected:
}
public:
/** Called by YAPF to calculate the cost from the origin to the given node.
/**
* Called by YAPF to calculate the cost from the origin to the given node.
* Calculates only the cost of given node, adds it to the parent node cost
* and stores the result into Node::m_cost member */
FORCEINLINE bool PfCalcCost(Node& n, const TrackFollower *tf)
@ -186,7 +187,8 @@ public:
return IsRoadDepotTile(tile);
}
/** Called by YAPF to calculate cost estimate. Calculates distance to the destination
/**
* Called by YAPF to calculate cost estimate. Calculates distance to the destination
* adds it to the actual cost from origin and stores the sum to the Node::m_estimate */
FORCEINLINE bool PfCalcEstimate(Node& n)
{
@ -254,7 +256,8 @@ public:
return tile == m_destTile && ((m_destTrackdirs & TrackdirToTrackdirBits(trackdir)) != TRACKDIR_BIT_NONE);
}
/** Called by YAPF to calculate cost estimate. Calculates distance to the destination
/**
* Called by YAPF to calculate cost estimate. Calculates distance to the destination
* adds it to the actual cost from origin and stores the sum to the Node::m_estimate */
inline bool PfCalcEstimate(Node& n)
{
@ -302,7 +305,8 @@ protected:
public:
/** Called by YAPF to move from the given node to the next tile. For each
/**
* Called by YAPF to move from the given node to the next tile. For each
* reachable trackdir on the new tile creates new node, initializes it
* and adds it to the open list by calling Yapf().AddNewNode(n) */
inline void PfFollowNode(Node& old_node)

9
src/pathfinder/yapf/yapf_ship.cpp
View File

@ -32,7 +32,8 @@ protected:
}
public:
/** Called by YAPF to move from the given node to the next tile. For each
/**
* Called by YAPF to move from the given node to the next tile. For each
* reachable trackdir on the new tile creates new node, initializes it
* and adds it to the open list by calling Yapf().AddNewNode(n) */
inline void PfFollowNode(Node& old_node)
@ -115,7 +116,8 @@ protected:
}
public:
/** Called by YAPF to calculate the cost from the origin to the given node.
/**
* Called by YAPF to calculate the cost from the origin to the given node.
* Calculates only the cost of given node, adds it to the parent node cost
* and stores the result into Node::m_cost member */
FORCEINLINE bool PfCalcCost(Node& n, const TrackFollower *tf)
@ -136,7 +138,8 @@ public:
}
};
/** Config struct of YAPF for ships.
/**
* Config struct of YAPF for ships.
* Defines all 6 base YAPF modules as classes providing services for CYapfBaseT.
*/
template <class Tpf_, class Ttrack_follower, class Tnode_list>

12
src/rail.h
View File

@ -80,7 +80,8 @@ enum RailTrackBridgeOffset {
RTBO_SLOPE, ///< Sloped rail pieces, in order NE, SE, SW, NW
};
/** Offsets from base sprite for fence sprites. These are in the order of
/**
* Offsets from base sprite for fence sprites. These are in the order of
* the sprites in the original data files.
*/
enum RailFenceOffset {
@ -94,10 +95,12 @@ enum RailFenceOffset {
RFO_SLOPE_NW,
};
/** This struct contains all the info that is needed to draw and construct tracks.
/**
* This struct contains all the info that is needed to draw and construct tracks.
*/
struct RailtypeInfo {
/** Struct containing the main sprites. @note not all sprites are listed, but only
/**
* Struct containing the main sprites. @note not all sprites are listed, but only
* the ones used directly in the code */
struct {
SpriteID track_y; ///< single piece of rail in Y direction, with ground
@ -114,7 +117,8 @@ struct RailtypeInfo {
SpriteID tunnel; ///< tunnel sprites base
} base_sprites;
/** struct containing the sprites for the rail GUI. @note only sprites referred to
/**
* struct containing the sprites for the rail GUI. @note only sprites referred to
* directly in the code are listed */
struct {
SpriteID build_ns_rail; ///< button for building single rail in N-S direction

48
src/rail_cmd.cpp
View File

@ -160,7 +160,8 @@ static CommandCost EnsureNoTrainOnTrack(TileIndex tile, Track track)
return EnsureNoTrainOnTrackBits(tile, rail_bits);
}
/** Check that the new track bits may be built.
/**
* Check that the new track bits may be built.
* @param tile %Tile to build on.
* @param to_build New track bits.
* @param flags Flags of the operation.
@ -350,7 +351,8 @@ static inline bool ValParamTrackOrientation(Track track)
return IsValidTrack(track);
}
/** Build a single piece of rail
/**
* Build a single piece of rail
* @param tile tile to build on
* @param flags operation to perform
* @param p1 railtype of being built piece (normal, mono, maglev)
@ -489,7 +491,8 @@ CommandCost CmdBuildSingleRail(TileIndex tile, DoCommandFlag flags, uint32 p1, u
return cost;
}
/** Remove a single piece of track
/**
* Remove a single piece of track
* @param tile tile to remove track from
* @param flags operation to perform
* @param p1 unused
@ -728,7 +731,8 @@ static CommandCost ValidateAutoDrag(Trackdir *trackdir, TileIndex start, TileInd
return CommandCost();
}
/** Build or remove a stretch of railroad tracks.
/**
* Build or remove a stretch of railroad tracks.
* @param tile start tile of drag
* @param flags operation to perform
* @param p1 end tile of drag
@ -788,7 +792,8 @@ static CommandCost CmdRailTrackHelper(TileIndex tile, DoCommandFlag flags, uint3
return last_error;
}
/** Build rail on a stretch of track.
/**
* Build rail on a stretch of track.
* Stub for the unified rail builder/remover
* @param tile start tile of drag
* @param flags operation to perform
@ -806,7 +811,8 @@ CommandCost CmdBuildRailroadTrack(TileIndex tile, DoCommandFlag flags, uint32 p1
return CmdRailTrackHelper(tile, flags, p1, ClrBit(p2, 7), text);
}
/** Build rail on a stretch of track.
/**
* Build rail on a stretch of track.
* Stub for the unified rail builder/remover
* @param tile start tile of drag
* @param flags operation to perform
@ -824,7 +830,8 @@ CommandCost CmdRemoveRailroadTrack(TileIndex tile, DoCommandFlag flags, uint32 p
return CmdRailTrackHelper(tile, flags, p1, SetBit(p2, 7), text);
}
/** Build a train depot
/**
* Build a train depot
* @param tile position of the train depot
* @param flags operation to perform
* @param p1 rail type
@ -884,7 +891,8 @@ CommandCost CmdBuildTrainDepot(TileIndex tile, DoCommandFlag flags, uint32 p1, u
return cost;
}
/** Build signals, alternate between double/single, signal/semaphore,
/**
* Build signals, alternate between double/single, signal/semaphore,
* pre/exit/combo-signals, and what-else not. If the rail piece does not
* have any signals, bit 4 (cycle signal-type) is ignored
* @param tile tile where to build the signals
@ -1116,7 +1124,8 @@ static bool CheckSignalAutoFill(TileIndex &tile, Trackdir &trackdir, int &signal
}
}
/** Build many signals by dragging; AutoSignals
/**
* Build many signals by dragging; AutoSignals
* @param tile start tile of drag
* @param flags operation to perform
* @param p1 end tile of drag
@ -1249,7 +1258,8 @@ static CommandCost CmdSignalTrackHelper(TileIndex tile, DoCommandFlag flags, uin
return had_success ? total_cost : last_error;
}
/** Build signals on a stretch of track.
/**
* Build signals on a stretch of track.
* Stub for the unified signal builder/remover
* @param tile start tile of drag
* @param flags operation to perform
@ -1271,7 +1281,8 @@ CommandCost CmdBuildSignalTrack(TileIndex tile, DoCommandFlag flags, uint32 p1,
return CmdSignalTrackHelper(tile, flags, p1, p2, text);
}
/** Remove signals
/**
* Remove signals
* @param tile coordinates where signal is being deleted from
* @param flags operation to perform
* @param p1 various bitstuffed elements, only track information is used
@ -1338,7 +1349,8 @@ CommandCost CmdRemoveSingleSignal(TileIndex tile, DoCommandFlag flags, uint32 p1
return CommandCost(EXPENSES_CONSTRUCTION, _price[PR_CLEAR_SIGNALS]);
}
/** Remove signals on a stretch of track.
/**
* Remove signals on a stretch of track.
* Stub for the unified signal builder/remover
* @param tile start tile of drag
* @param flags operation to perform
@ -1376,7 +1388,8 @@ static Vehicle *UpdateTrainPowerProc(Vehicle *v, void *data)
return NULL;
}
/** Convert one rail type to the other. You can convert normal rail to
/**
* Convert one rail type to the other. You can convert normal rail to
* monorail/maglev easily or vice-versa.
* @param tile end tile of rail conversion drag
* @param flags operation to perform
@ -2140,7 +2153,8 @@ static void DrawTrackBits(TileInfo *ti, TrackBits track)
}
}
/** Enums holding the offsets from base signal sprite,
/**
* Enums holding the offsets from base signal sprite,
* according to the side it is representing.
* The addtion of 2 per enum is necessary in order to "jump" over the
* green state sprite, all signal sprites being in pair,
@ -2682,7 +2696,8 @@ static const int8 _deltacoord_leaveoffset[8] = {
};
/** Compute number of ticks when next wagon will leave a depot.
/**
* Compute number of ticks when next wagon will leave a depot.
* Negative means next wagon should have left depot n ticks before.
* @param v vehicle outside (leaving) the depot
* @return number of ticks when the next wagon will leave
@ -2703,7 +2718,8 @@ int TicksToLeaveDepot(const Train *v)
return 0; // make compilers happy
}
/** Tile callback routine when vehicle enters tile
/**
* Tile callback routine when vehicle enters tile
* @see vehicle_enter_tile_proc */
static VehicleEnterTileStatus VehicleEnter_Track(Vehicle *u, TileIndex tile, int x, int y)
{

15
src/rail_gui.cpp
View File

@ -312,7 +312,8 @@ enum RailToolbarWidgets {
};
/** Toggles state of the Remove button of Build rail toolbar
/**
* Toggles state of the Remove button of Build rail toolbar
* @param w window the button belongs to
*/
static void ToggleRailButton_Remove(Window *w)
@ -324,7 +325,8 @@ static void ToggleRailButton_Remove(Window *w)
SetSelectionRed(_remove_button_clicked);
}
/** Updates the Remove button because of Ctrl state change
/**
* Updates the Remove button because of Ctrl state change
* @param w window the button belongs to
* @return true iff the remove buton was changed
*/
@ -635,7 +637,8 @@ struct BuildRailToolbarWindow : Window {
if (_settings_client.gui.link_terraform_toolbar) DeleteWindowById(WC_SCEN_LAND_GEN, 0, false);
}
/** Configures the rail toolbar for railtype given
/**
* Configures the rail toolbar for railtype given
* @param railtype the railtype to display
*/
void SetupRailToolbar(RailType railtype)
@ -654,7 +657,8 @@ struct BuildRailToolbarWindow : Window {
this->GetWidget<NWidgetCore>(RTW_BUILD_TUNNEL)->widget_data = rti->gui_sprites.build_tunnel;
}
/** Switch to another rail type.
/**
* Switch to another rail type.
* @param railtype New rail type.
*/
void ModifyRailType(RailType railtype)
@ -1939,7 +1943,8 @@ bool ResetSignalVariant(int32 p = 0)
return true;
}
/** Resets the rail GUI - sets default railtype to build
/**
* Resets the rail GUI - sets default railtype to build
* and resets the signal GUI
*/
void InitializeRailGUI()

Some files were not shown because too many files have changed in this diff Show More