Mercurial > hg > openttd
changeset 19843:9a8968c733ba draft
(svn r24776) -Doc: Typo fixes, additions, and additional dots collected from various sources (including Eagle_rainbow, MinchinWeb)
| author | alberth <alberth@openttd.org> |
|---|---|
| date | Sat, 01 Dec 2012 13:12:39 +0000 |
| parents | 480b2f1d4c02 |
| children | 9e7ae23544ad |
| files | src/cargotype.h src/core/bitmath_func.hpp src/core/overflowsafe_type.hpp src/core/random_func.hpp src/fontcache.cpp src/industry_gui.cpp src/main_gui.cpp src/map_type.h src/network/core/tcp_game.h src/network/network_gamelist.cpp src/network/network_gui.cpp src/newgrf_gui.cpp src/order_type.h src/roadstop.cpp src/saveload/afterload.cpp src/saveload/saveload.cpp src/script/api/script_group.hpp src/script/api/script_info_docs.hpp src/script/script_info_dummy.cpp src/settings_gui.cpp src/station.cpp src/tgp.cpp src/town_cmd.cpp |
| diffstat | 23 files changed, 79 insertions(+), 70 deletions(-) [+] |
line wrap: on
line diff
--- a/src/cargotype.h +++ b/src/cargotype.h @@ -157,8 +157,18 @@ #define FOR_EACH_SET_CARGO_ID(var, cargo_bits) FOR_EACH_SET_BIT_EX(CargoID, var, uint, cargo_bits) +/** + * Loop header for iterating over cargoes, sorted by name. This includes phony cargoes like regearing cargoes. + * @param var Reference getting the cargospec. + * @see CargoSpec + */ #define FOR_ALL_SORTED_CARGOSPECS(var) for (uint8 index = 0; var = _sorted_cargo_specs[index], index < _sorted_cargo_specs_size; index++) +/** + * Loop header for iterating over 'real' cargoes, sorted by name. Phony cargoes like regearing cargoes are skipped. + * @param var Reference getting the cargospec. + * @see CargoSpec + */ #define FOR_ALL_SORTED_STANDARD_CARGOSPECS(var) for (uint8 index = 0; var = _sorted_cargo_specs[index], index < _sorted_standard_cargo_specs_size; index++) #endif /* CARGOTYPE_H */
--- a/src/core/bitmath_func.hpp +++ b/src/core/bitmath_func.hpp @@ -13,18 +13,18 @@ #define BITMATH_FUNC_HPP /** - * Fetch n bits from x, started at bit s. + * Fetch \a n bits from \a x, started at bit \a s. * - * This function can be used to fetch n bits from the value x. The - * s value set the startposition to read. The startposition is - * count from the LSB and starts at 0. The result starts at a + * This function can be used to fetch \a n bits from the value \a x. The + * \a s value set the start position to read. The start position is + * count from the LSB and starts at \c 0. The result starts at a * LSB, as this isn't just an and-bitmask but also some * bit-shifting operations. GB(0xFF, 2, 1) will so * return 0x01 (0000 0001) instead of * 0x04 (0000 0100). * * @param x The value to read some bits. - * @param s The startposition to read some bits. + * @param s The start position to read some bits. * @param n The number of bits to read. * @return The selected bits, aligned to a LSB. */ @@ -44,10 +44,10 @@ * This is not a bug, its a feature. * * @note Parameter \a x must be a variable as the result is saved there. - * @note To avoid unexpecting results the value of \a d should not use more + * @note To avoid unexpected results the value of \a d should not use more * space as the provided space of \a n bits (log2) * @param x The variable to change some bits - * @param s The startposition for the new bits + * @param s The start position for the new bits * @param n The size/window for the new bits * @param d The actually new bits to save in the defined position. * @return The new value of \a x @@ -61,19 +61,19 @@ } /** - * Add i to n bits of x starting at bit s. + * Add \a i to \a n bits of \a x starting at bit \a 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 + * This adds the value of \a i on \a n bits of \a x starting at bit \a s. The parameters \a x, + * \a s, \a i are similar to #GB. Besides, \ a x must be a variable as the result are * saved there. An overflow does not affect the following bits of the given * bit window and is simply ignored. * * @note Parameter x must be a variable as the result is saved there. * @param x The variable to add some bits at some position - * @param s The startposition of the addition + * @param s The start position of the addition * @param n The size/window for the addition - * @param i The value to add at the given startposition in the given window. - * @return The new value of x + * @param i The value to add at the given start position in the given window. + * @return The new value of \a x */ template <typename T, typename U> static inline T AB(T &x, const uint8 s, const uint8 n, const U i) @@ -87,8 +87,8 @@ * Checks if a bit in a value is set. * * This function checks if a bit inside a value is set or not. - * The y value specific the position of the bit, started at the - * LSB and count from 0. + * The \a y value specific the position of the bit, started at the + * LSB and count from \c 0. * * @param x The value to check * @param y The position of the bit to check, started from the LSB @@ -165,7 +165,7 @@ * changed and the value is also returned. Parameter y defines the bit * to toggle and starts at the LSB with 0. * - * @param x The varliable to toggle the bit + * @param x The variable to toggle the bit * @param y The bit position to toggle * @return The new value of the old value with the bit toggled */ @@ -281,11 +281,11 @@ } /** - * ROtate x Left by n + * ROtate \a x Left by \a n * * @note Assumes a byte has 8 bits * @param x The value which we want to rotate - * @param n The number how many we waht to rotate + * @param n The number how many we want to rotate * @return A bit rotated number */ template <typename T> @@ -295,11 +295,11 @@ } /** - * ROtate x Right by n + * ROtate \a x Right by \a n * * @note Assumes a byte has 8 bits * @param x The value which we want to rotate - * @param n The number how many we waht to rotate + * @param n The number how many we want to rotate * @return A bit rotated number */ template <typename T>
--- a/src/core/overflowsafe_type.hpp +++ b/src/core/overflowsafe_type.hpp @@ -15,7 +15,7 @@ /** * Overflow safe template for integers, i.e. integers that will never overflow - * you multiply the maximum value with 2, or add 2, or substract somethng from + * you multiply the maximum value with 2, or add 2, or subtract something from * the minimum value, etc. * @param T the type these integers are stored with. * @param T_MAX the maximum value for the integers. @@ -54,7 +54,7 @@ return *this; } - /* Operators for addition and substraction */ + /* Operators for addition and subtraction */ inline OverflowSafeInt operator + (const OverflowSafeInt& other) const { OverflowSafeInt result = *this; result += other; return result; } inline OverflowSafeInt operator + (const int other) const { OverflowSafeInt result = *this; result += (int64)other; return result; } inline OverflowSafeInt operator + (const uint other) const { OverflowSafeInt result = *this; result += (int64)other; return result; }
--- a/src/core/random_func.hpp +++ b/src/core/random_func.hpp @@ -135,7 +135,7 @@ * This function uses the same parameters as Chance16. The third parameter * must be a variable the randomize-number from Random() is saved in. * - * The low 16 bits of r will already be used and can therefor not be passed to + * The low 16 bits of r will already be used and can therefore not be passed to * Chance16I. One can only send the high 16 bits to Chance16I. * * @see Chance16I()
--- a/src/fontcache.cpp +++ b/src/fontcache.cpp @@ -62,7 +62,7 @@ /** * Get the font loaded into a Freetype face by using a font-name. - * If no appropiate font is found, the function returns an error + * If no appropriate font is found, the function returns an error */ /* ========================================================================================
--- a/src/industry_gui.cpp +++ b/src/industry_gui.cpp @@ -109,7 +109,7 @@ } } -IndustryType _sorted_industry_types[NUM_INDUSTRYTYPES]; +IndustryType _sorted_industry_types[NUM_INDUSTRYTYPES]; ///< Industry types sorted by name. /** Sort industry types by their name. */ static int CDECL IndustryTypeNameSorter(const IndustryType *a, const IndustryType *b)
--- a/src/main_gui.cpp +++ b/src/main_gui.cpp @@ -441,7 +441,7 @@ virtual void OnInvalidateData(int data = 0, bool gui_scope = true) { if (!gui_scope) return; - /* Forward the message to the appropiate toolbar (ingame or scenario editor) */ + /* Forward the message to the appropriate toolbar (ingame or scenario editor) */ InvalidateWindowData(WC_MAIN_TOOLBAR, 0, data, true); }
--- a/src/map_type.h +++ b/src/map_type.h @@ -37,7 +37,7 @@ /** * An offset value between to tiles. * - * This value is used fro the difference between + * This value is used for the difference between * to tiles. It can be added to a tileindex to get * the resulting tileindex of the start tile applied * with this saved difference.
--- a/src/network/core/tcp_game.h +++ b/src/network/core/tcp_game.h @@ -29,7 +29,7 @@ /* * These first three pair of packets (thus six in * total) must remain in this order for backward - * and forward compatability between clients that + * and forward compatibility between clients that * are trying to join directly. */
--- a/src/network/network_gamelist.cpp +++ b/src/network/network_gamelist.cpp @@ -171,7 +171,7 @@ void NetworkAfterNewGRFScan() { for (NetworkGameList *item = _network_game_list; item != NULL; item = item->next) { - /* Reset compatability state */ + /* Reset compatibility state */ item->info.compatible = item->info.version_compatible; for (GRFConfig *c = item->info.grfconfig; c != NULL; c = c->next) { @@ -181,13 +181,13 @@ if (f == NULL) { /* Don't know the GRF, so mark game incompatible and the (possibly) * already resolved name for this GRF (another server has sent the - * name of the GRF already */ + * name of the GRF already. */ c->name->Release(); c->name = FindUnknownGRFName(c->ident.grfid, c->ident.md5sum, true); c->name->AddRef(); c->status = GCS_NOT_FOUND; - /* If we miss a file, we're obviously incompatible */ + /* If we miss a file, we're obviously incompatible. */ item->info.compatible = false; } else { c->filename = f->filename;
--- a/src/network/network_gui.cpp +++ b/src/network/network_gui.cpp @@ -72,7 +72,6 @@ /** * Update the network new window because a new server is * found on the network. - * @param unselect unselect the currently selected item */ void UpdateNetworkGameWindow() { @@ -850,7 +849,7 @@ this->server = this->servers[this->list_pos]; - /* scroll to the new server if it is outside the current range */ + /* Scroll to the new server if it is outside the current range. */ this->ScrollToSelectedServer(); /* redraw window */ @@ -1037,7 +1036,7 @@ /* Only show once */ if (first) { first = false; - /* add all servers from the config file to our list */ + /* Add all servers from the config file to our list. */ for (char **iter = _network_host_list.Begin(); iter != _network_host_list.End(); iter++) { NetworkAddServer(*iter); } @@ -1101,7 +1100,7 @@ { switch (widget) { case WID_NSS_SETPWD: - /* if password is set, draw red '*' next to 'Set password' button */ + /* If password is set, draw red '*' next to 'Set password' button. */ if (!StrEmpty(_settings_client.network.server_password)) DrawString(r.right + WD_FRAMERECT_LEFT, this->width - WD_FRAMERECT_RIGHT, r.top, "*", TC_RED); } } @@ -1126,7 +1125,7 @@ case WID_NSS_CLIENTS_BTND: case WID_NSS_CLIENTS_BTNU: // Click on up/down button for number of clients case WID_NSS_COMPANIES_BTND: case WID_NSS_COMPANIES_BTNU: // Click on up/down button for number of companies case WID_NSS_SPECTATORS_BTND: case WID_NSS_SPECTATORS_BTNU: // Click on up/down button for number of spectators - /* Don't allow too fast scrolling */ + /* Don't allow too fast scrolling. */ if (!(this->flags & WF_TIMEOUT) || this->timeout_timer <= 1) { this->HandleButtonClick(widget); this->SetDirty(); @@ -1353,7 +1352,7 @@ } struct NetworkLobbyWindow : public Window { - CompanyID company; ///< Select company + CompanyID company; ///< Selected company NetworkGameList *server; ///< Selected server NetworkCompanyInfo company_info[MAX_COMPANIES]; Scrollbar *vscroll; @@ -1369,7 +1368,7 @@ CompanyID NetworkLobbyFindCompanyIndex(byte pos) const { - /* Scroll through all this->company_info and get the 'pos' item that is not empty */ + /* Scroll through all this->company_info and get the 'pos' item that is not empty. */ for (CompanyID i = COMPANY_FIRST; i < MAX_COMPANIES; i++) { if (!StrEmpty(this->company_info[i].company_name)) { if (pos-- == 0) return i; @@ -1423,11 +1422,11 @@ { const NetworkGameInfo *gi = &this->server->info; - /* Join button is disabled when no company is selected and for AI companies*/ + /* Join button is disabled when no company is selected and for AI companies. */ this->SetWidgetDisabledState(WID_NL_JOIN, this->company == INVALID_COMPANY || GetLobbyCompanyInfo(this->company)->ai); - /* Cannot start new company if there are too many */ + /* Cannot start new company if there are too many. */ this->SetWidgetDisabledState(WID_NL_NEW, gi->companies_on >= gi->companies_max); - /* Cannot spectate if there are too many spectators */ + /* Cannot spectate if there are too many spectators. */ this->SetWidgetDisabledState(WID_NL_SPECTATE, gi->spectators_on >= gi->spectators_max); this->vscroll->SetCount(gi->companies_on); @@ -1481,7 +1480,7 @@ void DrawDetails(const Rect &r) const { const int detail_height = 12 + FONT_HEIGHT_NORMAL + 12; - /* Draw info about selected company when it is selected in the left window */ + /* Draw info about selected company when it is selected in the left window. */ GfxFillRect(r.left + 1, r.top + 1, r.right - 1, r.top + detail_height - 1, PC_DARK_BLUE); DrawString(r.left + WD_FRAMERECT_LEFT, r.right - WD_FRAMERECT_RIGHT, r.top + 12, STR_NETWORK_GAME_LOBBY_COMPANY_INFO, TC_FROMSTRING, SA_HOR_CENTER); @@ -1559,7 +1558,7 @@ } case WID_NL_JOIN: // Join company - /* Button can be clicked only when it is enabled */ + /* Button can be clicked only when it is enabled. */ NetworkClientConnectGame(NetworkAddress(_settings_client.network.last_host, _settings_client.network.last_port), this->company); break; @@ -1757,13 +1756,13 @@ this->AddAction(STR_NETWORK_CLIENTLIST_SPEAK_TO_ALL, &ClientList_SpeakToAll); if (_network_own_client_id != ci->client_id) { - /* We are no spectator and the company we want to give money to is no spectator and money gifts are allowed */ + /* We are no spectator and the company we want to give money to is no spectator and money gifts are allowed. */ if (Company::IsValidID(_local_company) && Company::IsValidID(ci->client_playas) && _settings_game.economy.give_money) { this->AddAction(STR_NETWORK_CLIENTLIST_GIVE_MONEY, &ClientList_GiveMoney); } } - /* A server can kick clients (but not himself) */ + /* A server can kick clients (but not himself). */ if (_network_server && _network_own_client_id != ci->client_id) { this->AddAction(STR_NETWORK_CLIENTLIST_KICK, &ClientList_Kick); this->AddAction(STR_NETWORK_CLIENTLIST_BAN, &ClientList_Ban);
--- a/src/newgrf_gui.cpp +++ b/src/newgrf_gui.cpp @@ -1399,7 +1399,7 @@ const GRFConfig *best = FindGRFConfig(c->ident.grfid, HasBit(c->flags, GCF_INVALID) ? FGCM_NEWEST : FGCM_NEWEST_VALID); /* * If the best version is 0, then all NewGRF with this GRF ID - * have version 0, so for backward compatability reasons we + * have version 0, so for backward compatibility reasons we * want to show them all. * If we are the best version, then we definitely want to * show that NewGRF!.
--- a/src/order_type.h +++ b/src/order_type.h @@ -61,8 +61,8 @@ */ enum OrderLoadFlags { OLF_LOAD_IF_POSSIBLE = 0, ///< Load as long as there is cargo that fits in the train. - OLFB_FULL_LOAD = 1 << 1, ///< Full load the complete the consist. - OLF_FULL_LOAD_ANY = 3, ///< Full load the a single cargo of the consist. + OLFB_FULL_LOAD = 1 << 1, ///< Full load all cargoes of the consist. + OLF_FULL_LOAD_ANY = 3, ///< Full load a single cargo of the consist. OLFB_NO_LOAD = 4, ///< Do not load anything. }; @@ -137,7 +137,7 @@ /** - * Enumeration for the data to set in CmdModifyOrder. + * Enumeration for the data to set in #CmdModifyOrder. */ enum ModifyOrderFlags { MOF_NON_STOP, ///< Passes an OrderNonStopFlags. @@ -154,7 +154,7 @@ template <> struct EnumPropsT<ModifyOrderFlags> : MakeEnumPropsT<ModifyOrderFlags, byte, MOF_NON_STOP, MOF_END, MOF_END, 4> {}; /** - * Depot action to switch to when doing a MOF_DEPOT_ACTION. + * Depot action to switch to when doing a #MOF_DEPOT_ACTION. */ enum OrderDepotAction { DA_ALWAYS_GO, ///< Always go to the depot @@ -164,7 +164,7 @@ }; /** - * Enumeration for the data to set in CmdChangeTimetable. + * Enumeration for the data to set in #CmdChangeTimetable. */ enum ModifyTimetableFlags { MTF_WAIT_TIME, ///< Set wait time. @@ -175,7 +175,7 @@ template <> struct EnumPropsT<ModifyTimetableFlags> : MakeEnumPropsT<ModifyTimetableFlags, byte, MTF_WAIT_TIME, MTF_END, MTF_END, 2> {}; -/* Possible clone options */ +/** Clone actions. */ enum CloneOptions { CO_SHARE = 0, CO_COPY = 1,
--- a/src/roadstop.cpp +++ b/src/roadstop.cpp @@ -44,7 +44,7 @@ for (RoadStop *rs = this->next; rs != NULL; rs = rs->next) { /* The vehicle cannot go to this roadstop (different roadtype) */ if ((GetRoadTypes(rs->xy) & v->compatible_roadtypes) == ROADTYPES_NONE) continue; - /* The vehicle is articulated and can therefor not go the a standard road stop */ + /* The vehicle is articulated and can therefore not go to a standard road stop. */ if (IsStandardRoadStopTile(rs->xy) && v->HasArticulatedPart()) continue; /* The vehicle can actually go to this road stop. So, return it! */
--- a/src/saveload/afterload.cpp +++ b/src/saveload/afterload.cpp @@ -636,7 +636,7 @@ SetDate(_date, _date_fract); /* - * Force the old behaviour for compatability reasons with old savegames. + * Force the old behaviour for compatibility reasons with old savegames. * * Note that there is no non-stop in here. This is because the setting could have * either value in TTDPatch. To convert it properly the user has to make sure the
--- a/src/saveload/saveload.cpp +++ b/src/saveload/saveload.cpp @@ -1218,7 +1218,7 @@ /** * Pointers cannot be loaded from a savegame, so this function - * gets the index from the savegame and returns the appropiate + * gets the index from the savegame and returns the appropriate * pointer from the already loaded base. * Remember that an index of 0 is a NULL pointer so all indices * are +1 so vehicle 0 is saved as 1. @@ -1675,7 +1675,7 @@ /** * Save a chunk of data (eg. vehicles, stations, etc.). Each chunk is - * prefixed by an ID identifying it, followed by data, and terminator where appropiate + * prefixed by an ID identifying it, followed by data, and terminator where appropriate * @param ch The chunkhandler that will be used for the operation */ static void SlSaveChunk(const ChunkHandler *ch) @@ -1730,7 +1730,7 @@ * Find the ChunkHandler that will be used for processing the found * chunk in the savegame or in memory * @param id the chunk in question - * @return returns the appropiate chunkhandler + * @return returns the appropriate chunkhandler */ static const ChunkHandler *SlFindChunkHandler(uint32 id) { @@ -2408,7 +2408,7 @@ /** * We have written the whole game into memory, _memory_savegame, now find - * and appropiate compressor and start writing to file. + * and appropriate compressor and start writing to file. */ static SaveOrLoadResult SaveFileToDisk(bool threaded) {
--- a/src/script/api/script_group.hpp +++ b/src/script/api/script_group.hpp @@ -113,7 +113,7 @@ /** * Move a vehicle to a group. - * @param group_id The group to move the vehicel to. + * @param group_id The group to move the vehicle to. * @param vehicle_id The vehicle to move to the group. * @pre IsValidGroup(group_id) || group_id == GROUP_DEFAULT. * @pre ScriptVehicle::IsValidVehicle(vehicle_id). @@ -129,7 +129,7 @@ * (auto)replaced with a longer variant (longer wagons or longer engines) * If enabled, wagons are removed from the end of the vehicle until it * fits in the same number of tiles as it did before. - * @param keep_length If true, wagons will be removed if the a new engine is longer. + * @param keep_length If true, wagons will be removed if the new engine is longer. * @return True if and only if the value was successfully changed. */ static bool EnableWagonRemoval(bool keep_length);
--- a/src/script/api/script_info_docs.hpp +++ b/src/script/api/script_info_docs.hpp @@ -133,7 +133,7 @@ * Can a non-developer select Script for a new game. * * The idea behind this function is to 'forbid' using your script with a new - * game if you for example specificly wrote it for a certain scenario. + * game if you for example specifically wrote it for a certain scenario. * * @return True if the Script can be selected from the GUI as non-developer. * @note This function is optional. Default is false. @@ -153,13 +153,13 @@ /** * Gets the API version this Script is written for. If this function - * does not exist API compatability with version 0.7 is assumed. + * does not exist API compatibility with version 0.7 is assumed. * If the function returns something OpenTTD does not understand, * for example a newer version or a string that is not a version, * the Script will not be loaded. * * Although in the future we might need to make a separate - * compatability 'wrapper' for a specific version of OpenTTD, for + * compatibility 'wrapper' for a specific version of OpenTTD, for * example '0.7.1', we will use only the major and minor number * and not the bugfix number as valid return for this function. * @@ -246,7 +246,7 @@ * @param setting_name The name of the setting. * @param value_names A table that maps values to names. The first * character of every identifier is ignored and the rest should - * be the an integer of the value you define a name for. The value + * be an integer of the value you define a name for. The value * is a short description of that value. * To define labels for a setting named "competition_level" you could * for example call it like this:
--- a/src/script/script_info_dummy.cpp +++ b/src/script/script_info_dummy.cpp @@ -17,9 +17,9 @@ /* The reason this exists in C++, is that a user can trash his ai/ or game/ dir, * leaving no Scripts available. The complexity to solve this is insane, and - * therefor the alternative is used, and make sure there is always a Script + * therefore the alternative is used, and make sure there is always a Script * available, no matter what the situation is. By defining it in C++, there - * is simply no way a user can delete it, and therefor safe to use. It has + * is simply no way a user can delete it, and therefore safe to use. It has * to be noted that this Script is complete invisible for the user, and impossible * to select manual. It is a fail-over in case no Scripts are available. */
--- a/src/settings_gui.cpp +++ b/src/settings_gui.cpp @@ -1396,7 +1396,7 @@ * | |-- setting * \endverbatim * The left-most vertical line is not wanted. It is prevented by setting the - * appropiate bit in the \a parent_last parameter. + * appropriate bit in the \a parent_last parameter. * * @param settings_ptr Pointer to current values of all settings * @param left Left-most position in window/panel to start drawing \a first_row
--- a/src/station.cpp +++ b/src/station.cpp @@ -143,7 +143,7 @@ for (; rs != NULL; rs = rs->next) { /* The vehicle cannot go to this roadstop (different roadtype) */ if ((GetRoadTypes(rs->xy) & v->compatible_roadtypes) == ROADTYPES_NONE) continue; - /* The vehicle is articulated and can therefor not go the a standard road stop */ + /* The vehicle is articulated and can therefore not go to a standard road stop. */ if (IsStandardRoadStopTile(rs->xy) && v->HasArticulatedPart()) continue; /* The vehicle can actually go to this road stop. So, return it! */
--- a/src/tgp.cpp +++ b/src/tgp.cpp @@ -290,7 +290,7 @@ * One interpolation and noise round * * The heights on the map are generated in an iterative process. - * We start off with a frequency of 1 (log_frequency == 0), and generate heights only for corners on the most coarsely mesh + * We start off with a frequency of 1 (log_frequency == 0), and generate heights only for corners on the most coarsest mesh * (i.e. only for x/y coordinates which are multiples of the minimum edge length). * * After this initial step the frequency is doubled (log_frequency incremented) each iteration to generate corners on the next finer mesh.