diff --git a/src/bridge.h b/src/bridge.h --- a/src/bridge.h +++ b/src/bridge.h @@ -33,9 +33,9 @@ enum BridgePieces { DECLARE_POSTFIX_INCREMENT(BridgePieces) -static const uint MAX_BRIDGES = 13; +static const uint MAX_BRIDGES = 13; ///< Maximal number of available bridge specs. -typedef uint BridgeType; +typedef uint BridgeType; ///< Bridge spec number. /** * Struct containing information about a single bridge type diff --git a/src/bridge_gui.cpp b/src/bridge_gui.cpp --- a/src/bridge_gui.cpp +++ b/src/bridge_gui.cpp @@ -39,7 +39,7 @@ struct BuildBridgeData { Money cost; }; -typedef GUIList GUIBridgeList; +typedef GUIList GUIBridgeList; ///< List of bridges, used in #BuildBridgeWindow. /** * Callback executed after a build Bridge CMD has been called @@ -63,11 +63,12 @@ enum BuildBridgeSelectionWidgets { BBSW_SCROLLBAR, }; +/** Window class for handling the bridge-build GUI. */ class BuildBridgeWindow : public Window { private: /* Runtime saved values */ - static uint16 last_size; - static Listing last_sorting; + static uint16 last_size; ///< Last size of the bridge GUI window. + static Listing last_sorting; ///< Last setting of the sort. /* Constants for sorting the bridges */ static const StringID sorter_names[]; @@ -287,19 +288,19 @@ public: } }; -/* Set the default size of the Build Bridge Window */ +/** Set the default size of the Build Bridge Window. */ uint16 BuildBridgeWindow::last_size = 4; -/* Set the default sorting for the bridges */ +/** Set the default sorting for the bridges */ Listing BuildBridgeWindow::last_sorting = {false, 0}; -/* Availible bridge sorting functions */ +/** Available bridge sorting functions. */ GUIBridgeList::SortFunction * const BuildBridgeWindow::sorter_funcs[] = { &BridgeIndexSorter, &BridgePriceSorter, &BridgeSpeedSorter }; -/* Names of the sorting functions */ +/** Names of the sorting functions. */ const StringID BuildBridgeWindow::sorter_names[] = { STR_SORT_BY_NUMBER, STR_SORT_BY_COST, @@ -307,6 +308,7 @@ const StringID BuildBridgeWindow::sorter INVALID_STRING_ID }; +/** Widgets of the bridge gui. */ static const NWidgetPart _nested_build_bridge_widgets[] = { /* Header */ NWidget(NWID_HORIZONTAL), @@ -333,7 +335,7 @@ static const NWidgetPart _nested_build_b EndContainer(), }; -/* Window definition for the rail bridge selection window */ +/** Window definition for the rail bridge selection window. */ static const WindowDesc _build_bridge_desc( WDP_AUTO, 200, 114, WC_BUILD_BRIDGE, WC_BUILD_TOOLBAR, diff --git a/src/industry_cmd.cpp b/src/industry_cmd.cpp --- a/src/industry_cmd.cpp +++ b/src/industry_cmd.cpp @@ -1043,10 +1043,10 @@ static void ChopLumberMillTrees(Industry { TileIndex tile = i->location.tile; - if (!IsIndustryCompleted(tile)) return; ///< Can't proceed if not completed - - if (CircularTileSearch(&tile, 40, SearchLumberMillTrees, NULL)) { ///< 40x40 tiles to search - i->produced_cargo_waiting[0] = min(0xffff, i->produced_cargo_waiting[0] + 45); ///< Found a tree, add according value to waiting cargo + if (!IsIndustryCompleted(tile)) return; // Can't proceed if not completed. + + if (CircularTileSearch(&tile, 40, SearchLumberMillTrees, NULL)) { // 40x40 tiles to search. + i->produced_cargo_waiting[0] = min(0xffff, i->produced_cargo_waiting[0] + 45); // Found a tree, add according value to waiting cargo. } } diff --git a/src/newgrf_industries.cpp b/src/newgrf_industries.cpp --- a/src/newgrf_industries.cpp +++ b/src/newgrf_industries.cpp @@ -506,6 +506,12 @@ CommandCost CheckIfCallBackAllowsCreatio NOT_REACHED(); } +/** + * Check with callback #CBM_IND_AVAILABLE whether the industry can be built. + * @param type Industry type to check. + * @param creation_type Reason to construct a new industry. + * @return If the industry has no callback or allows building, \c true is returned. Otherwise, \c false is returned. + */ bool CheckIfCallBackAllowsAvailability(IndustryType type, IndustryAvailabilityCallType creation_type) { const IndustrySpec *indspec = GetIndustrySpec(type); diff --git a/src/newgrf_station.cpp b/src/newgrf_station.cpp --- a/src/newgrf_station.cpp +++ b/src/newgrf_station.cpp @@ -89,12 +89,17 @@ struct ETileArea : TileArea { }; -/* Evaluate a tile's position within a station, and return the result a bit-stuffed format. +/** + * Evaluate a tile's position within a station, and return the result in a bit-stuffed format. * if not centered: .TNLcCpP, if centered: .TNL..CP - * T = Tile layout number (#GetStationGfx), N = Number of platforms, L = Length of platforms - * C = Current platform number from start, c = from end - * P = Position along platform from start, p = from end + * - T = Tile layout number (#GetStationGfx) + * - N = Number of platforms + * - L = Length of platforms + * - C = Current platform number from start, c = from end + * - P = Position along platform from start, p = from end + * . * if centered, C/P start from the centre and c/p are not available. + * @return Platform information in bit-stuffed format. */ uint32 GetPlatformInfo(Axis axis, byte tile, int platforms, int length, int x, int y, bool centred) { @@ -129,9 +134,13 @@ uint32 GetPlatformInfo(Axis axis, byte t } -/* Find the end of a railway station, from the tile, in the direction of delta. - * If check_type is set, we stop if the custom station type changes. - * If check_axis is set, we stop if the station direction changes. +/** + * Find the end of a railway station, from the \a tile, in the direction of \a delta. + * @param tile Start tile. + * @param delta Movement direction. + * @param check_type Stop when the custom station type changes. + * @param check_axis Stop when the station direction changes. + * @return Found end of the railway station. */ static TileIndex FindRailStationEnd(TileIndex tile, TileIndexDiff delta, bool check_type, bool check_axis) { @@ -785,8 +794,12 @@ const StationSpec *GetStationSpec(TileIn } -/* Check if a rail station tile is traversable. - * XXX This could be cached (during build) in the map array to save on all the dereferencing */ +/** + * Check whether a rail station tile is NOT traversable. + * @param tile %Tile to test. + * @return Station tile is blocked. + * @note This could be cached (during build) in the map array to save on all the dereferencing. + */ bool IsStationTileBlocked(TileIndex tile) { const StationSpec *statspec = GetStationSpec(tile); @@ -794,8 +807,12 @@ bool IsStationTileBlocked(TileIndex tile return statspec != NULL && HasBit(statspec->blocked, GetStationGfx(tile)); } -/* Check if a rail station tile is electrifiable. - * XXX This could be cached (during build) in the map array to save on all the dereferencing */ +/** + * Check if a rail station tile can be electrified. + * @param tile %Tile to test. + * @return Tile can be electrified. + * @note This could be cached (during build) in the map array to save on all the dereferencing. + */ bool IsStationTileElectrifiable(TileIndex tile) { const StationSpec *statspec = GetStationSpec(tile); diff --git a/src/order_type.h b/src/order_type.h --- a/src/order_type.h +++ b/src/order_type.h @@ -27,7 +27,7 @@ static const VehicleOrderID MAX_VEH_ORDE /** Invalid order (sentinel) */ static const OrderID INVALID_ORDER = 0xFFFF; -/* Order types */ +/** Order types */ enum OrderType { OT_BEGIN = 0, OT_NOTHING = 0, diff --git a/src/saveload/saveload.cpp b/src/saveload/saveload.cpp --- a/src/saveload/saveload.cpp +++ b/src/saveload/saveload.cpp @@ -13,8 +13,8 @@ * are as follows for saving a game (loading is analogous): *
    *
  1. initialize the writer by creating a temporary memory-buffer for it - *
  2. go through all to-be saved elements, each 'chunk' (ChunkHandler) prefixed by a label - *
  3. use their description array (SaveLoad) to know what elements to save and in what version + *
  4. go through all to-be saved elements, each 'chunk' (#ChunkHandler) prefixed by a label + *
  5. use their description array (#SaveLoad) to know what elements to save and in what version * of the game it was active (used when loading) *
  6. write all data byte-by-byte to the temporary buffer so it is endian-safe *
  7. when the buffer is full; flush it to the output (eg save to file) (_sl.buf, _sl.bufp, _sl.bufe) diff --git a/src/station_cmd.cpp b/src/station_cmd.cpp --- a/src/station_cmd.cpp +++ b/src/station_cmd.cpp @@ -1546,7 +1546,7 @@ CommandCost CmdRemoveFromRailWaypoint(Ti /** - * Remove a rail road station/waypoint + * Remove a rail station/waypoint * @param st The station/waypoint to remove the rail part from * @param flags operation to perform * @tparam T the type of station to remove @@ -1614,7 +1614,7 @@ CommandCost RemoveRailStation(T *st, DoC } /** - * Remove a rail road station + * Remove a rail station * @param tile TileIndex been queried * @param flags operation to perform * @return cost or failure of operation diff --git a/src/viewport_func.h b/src/viewport_func.h --- a/src/viewport_func.h +++ b/src/viewport_func.h @@ -40,6 +40,12 @@ void ZoomInOrOutToCursorWindow(bool in, Point GetTileZoomCenterWindow(bool in, Window * w); void HandleZoomMessage(Window *w, const ViewPort *vp, byte widget_zoom_in, byte widget_zoom_out); +/** + * Zoom a viewport as far as possible in the given direction. + * @param how Zooming direction. + * @param w Window owning the viewport. + * @pre \a how should not be #ZOOM_NONE. + */ static inline void MaxZoomInOut(ZoomStateChange how, Window *w) { while (DoZoomInOutWindow(how, w)) {};