diff --git a/src/news_func.h b/src/news_func.h index 2d35d22d75..0a815dcee6 100644 --- a/src/news_func.h +++ b/src/news_func.h @@ -24,8 +24,10 @@ inline void AddCompanyNewsItem(EncodedString &&headline, std::unique_ptrtype)].sound; @@ -701,7 +704,10 @@ static void ShowNewspaper(const NewsItem *ni) new NewsWindow(GetNewsWindowLayout(ni->style), ni); } -/** Show news item in the ticker */ +/** + * Show news item in the ticker. + * @param ni Iterator to the news message to show. + */ static void ShowTicker(NewsIterator ni) { if (_settings_client.sound.news_ticker) SndPlayFx(SND_16_NEWS_TICKER); @@ -723,6 +729,7 @@ void InitNewsItemStructs() /** * Are we ready to show another ticker item? * Only if nothing is in the newsticker is displayed + * @return \c true iff there is no news item or the ticker of the current news item has been shown. */ static bool ReadyForNextTickerItem() { @@ -737,6 +744,7 @@ static bool ReadyForNextTickerItem() /** * Are we ready to show another news item? * Only if no newspaper is displayed + * @return \c true iff there is neither a ticker not a newspaper being shown. */ static bool ReadyForNextNewsItem() { @@ -818,7 +826,11 @@ static void MoveToNextNewsItem() } } -/** Delete a news item from the queue */ +/** + * Delete a news item from the queue + * @param ni Iterator pointing to the news item to remove. + * @return The updates iterator after removal. + */ static std::list::iterator DeleteNewsItem(std::list::iterator ni) { bool update_current_news = (_forced_news == ni || _current_news == ni); @@ -976,6 +988,7 @@ CommandCost CmdCustomNewsItem(DoCommandFlags flags, NewsType type, CompanyID com * Delete news items by predicate, and invalidate the message history if necessary. * @tparam Tmin Stop if the number of news items remaining reaches \a min items. * @tparam Tpredicate Condition for a news item to be deleted. + * @param predicate The predicate to apply when iterating the news. */ template void DeleteNews(Tpredicate predicate) @@ -1106,7 +1119,10 @@ void NewsLoop() if (ReadyForNextNewsItem()) MoveToNextNewsItem(); } -/** Do a forced show of a specific message */ +/** + * Do a forced show of a specific message. + * @param ni Iterator to the news message to show. + */ static void ShowNewsMessage(NewsIterator ni) { assert(!std::empty(_news)); diff --git a/src/object_base.h b/src/object_base.h index 327b722710..d2b5747df6 100644 --- a/src/object_base.h +++ b/src/object_base.h @@ -62,6 +62,7 @@ struct Object : ObjectPool::PoolItem<&_object_pool> { * Get the count of objects for this type. * @param type ObjectType to query * @pre type < NUM_OBJECTS + * @return The number of objects of the given type. */ static inline uint16_t GetTypeCount(ObjectType type) { diff --git a/src/object_gui.cpp b/src/object_gui.cpp index 85298e9681..d56068445b 100644 --- a/src/object_gui.cpp +++ b/src/object_gui.cpp @@ -416,7 +416,10 @@ static WindowDesc _build_object_desc( &BuildObjectWindow::hotkeys ); -/** Show our object picker. */ +/** + * Show our object picker. + * @return The allocated window or \c nullptr when no window was allocated. + */ Window *ShowBuildObjectPicker() { /* Don't show the place object button when there are no objects to place. */ diff --git a/src/openttd.cpp b/src/openttd.cpp index 9652a8dcbc..b638ef38e6 100644 --- a/src/openttd.cpp +++ b/src/openttd.cpp @@ -934,6 +934,7 @@ static void MakeNewEditorWorld() * @param newgm switch to this mode of loading fails due to some unknown error * @param subdir default directory to look for filename, set to 0 if not needed * @param lf Load filter to use, if nullptr: use filename + subdir. + * @return \c true iff the save was loaded without problems. */ bool SafeLoad(const std::string &filename, SaveLoadOperation fop, DetailedFileType dft, GameMode newgm, Subdirectory subdir, std::shared_ptr lf = nullptr) { diff --git a/src/order_base.h b/src/order_base.h index e3e3480d7b..14d2ebe043 100644 --- a/src/order_base.h +++ b/src/order_base.h @@ -138,46 +138,124 @@ public: return type == OrderLoadType::FullLoad || type == OrderLoadType::FullLoadAny; } - /** How must the consist be loaded? */ + /** + * How must the consist be loaded? + * @return The way to load the vehicle. + */ inline OrderLoadType GetLoadType() const { return static_cast(GB(this->flags, 4, 3)); } - /** How must the consist be unloaded? */ + + /** + * How must the consist be unloaded? + * @return The way to unload the vehicle. + */ inline OrderUnloadType GetUnloadType() const { return static_cast(GB(this->flags, 0, 3)); } - /** At which stations must we stop? */ + + /** + * At which stations must we stop? + * @return Which stations to stop at. + */ inline OrderNonStopFlags GetNonStopType() const { return static_cast(GB(this->type, 6, 2)); } - /** Where must we stop at the platform? */ + + /** + * Where must we stop at the platform? + * @return Where at the platform to stop. + */ inline OrderStopLocation GetStopLocation() const { return static_cast(GB(this->type, 4, 2)); } - /** What caused us going to the depot? */ + + /** + * What caused us going to the depot? + * @return The reason to go to the depot. + */ inline OrderDepotTypeFlags GetDepotOrderType() const { return static_cast(GB(this->flags, 0, 3)); } - /** What are we going to do when in the depot. */ + + /** + * What are we going to do when in the depot. + * @return What to do in the depot. + */ inline OrderDepotActionFlags GetDepotActionType() const { return static_cast(GB(this->flags, 3, 4)); } - /** What variable do we have to compare? */ + + /** + * What variable do we have to compare? + * @return The variable of the comparison. + */ inline OrderConditionVariable GetConditionVariable() const { return static_cast(GB(this->dest.value, 11, 5)); } - /** What is the comparator to use? */ + + /** + * What is the comparator to use? + * @return The comparator for the comparison. + */ inline OrderConditionComparator GetConditionComparator() const { return static_cast(GB(this->type, 5, 3)); } - /** Get the order to skip to. */ + + /** + * Get the order to skip to. + * @return The sub-order to skip to. + */ inline VehicleOrderID GetConditionSkipToOrder() const { return this->flags; } - /** Get the value to base the skip on. */ + + /** + * Get the value to base the skip on. + * @return The value to compare the variable against. + */ inline uint16_t GetConditionValue() const { return GB(this->dest.value, 0, 11); } - /** Set how the consist must be loaded. */ + /** + * Set how the consist must be loaded. + * @param load_type The new load type, i.e. whether to load. + */ inline void SetLoadType(OrderLoadType load_type) { SB(this->flags, 4, 3, to_underlying(load_type)); } - /** Set how the consist must be unloaded. */ + + /** + * Set how the consist must be unloaded. + * @param unload_type The new unload type, i.e. whether to unload. + */ inline void SetUnloadType(OrderUnloadType unload_type) { SB(this->flags, 0, 3, to_underlying(unload_type)); } - /** Set whether we must stop at stations or not. */ + + /** + * Set whether we must stop at stations or not. + * @param non_stop_type The new non stop type, i.e. where to stop. + */ inline void SetNonStopType(OrderNonStopFlags non_stop_type) { SB(this->type, 6, 2, non_stop_type.base()); } - /** Set where we must stop at the platform. */ + + /** + * Set where we must stop at the platform. + * @param stop_location The location to stop at. + */ inline void SetStopLocation(OrderStopLocation stop_location) { SB(this->type, 4, 2, to_underlying(stop_location)); } - /** Set the cause to go to the depot. */ + + /** + * Set the cause to go to the depot. + * @param depot_order_type The reason to go to the depot. + */ inline void SetDepotOrderType(OrderDepotTypeFlags depot_order_type) { SB(this->flags, 0, 3, depot_order_type.base()); } - /** Set what we are going to do in the depot. */ + + /** + * Set what we are going to do in the depot. + * @param depot_service_type What to do in the depot. + */ inline void SetDepotActionType(OrderDepotActionFlags depot_service_type) { SB(this->flags, 3, 4, depot_service_type.base()); } - /** Set variable we have to compare. */ + + /** + * Set variable we have to compare. + * @param condition_variable The new variable to compare on. + */ inline void SetConditionVariable(OrderConditionVariable condition_variable) { SB(this->dest.value, 11, 5, to_underlying(condition_variable)); } - /** Set the comparator to use. */ + + /** + * Set the comparator to use. + * @param condition_comparator The new comparator to compare with. + */ inline void SetConditionComparator(OrderConditionComparator condition_comparator) { SB(this->type, 5, 3, to_underlying(condition_comparator)); } - /** Get the order to skip to. */ + + /** + * Get the order to skip to. + * @param order_id The new order to skip to. + */ inline void SetConditionSkipToOrder(VehicleOrderID order_id) { this->flags = order_id; } - /** Set the value to base the skip on. */ + + /** + * Set the value to base the skip on. + * @param value The new value to compare against. + */ inline void SetConditionValue(uint16_t value) { SB(this->dest.value, 0, 11, value); } /* As conditional orders write their "skip to" order all over the flags, we cannot check the @@ -185,18 +263,39 @@ public: * autofilled we can be sure that any non-zero values for their wait_time and travel_time are * explicitly set (but travel_time is actually unused for conditionals). */ - /** Does this order have an explicit wait time set? */ + /** + * Does this order have an explicit wait time set? + * @return \c true iff the wait time has been set. + */ inline bool IsWaitTimetabled() const { return this->IsType(OT_CONDITIONAL) ? this->wait_time > 0 : HasBit(this->flags, 3); } - /** Does this order have an explicit travel time set? */ + + /** + * Does this order have an explicit travel time set? + * @return \c true iff the travel time has been set. + */ inline bool IsTravelTimetabled() const { return this->IsType(OT_CONDITIONAL) ? this->travel_time > 0 : HasBit(this->flags, 7); } - /** Get the time in ticks a vehicle should wait at the destination or 0 if it's not timetabled. */ + /** + * Get the time in ticks a vehicle should wait at the destination or 0 if it's not timetabled. + * @return The wait time when explicitly timetabled, otherwise \c 0. + */ inline uint16_t GetTimetabledWait() const { return this->IsWaitTimetabled() ? this->wait_time : 0; } - /** Get the time in ticks a vehicle should take to reach the destination or 0 if it's not timetabled. */ + /** + * Get the time in ticks a vehicle should take to reach the destination or 0 if it's not timetabled. + * @return The travel time when explicitly timetabled, otherwise \c 0. + */ inline uint16_t GetTimetabledTravel() const { return this->IsTravelTimetabled() ? this->travel_time : 0; } - /** Get the time in ticks a vehicle will probably wait at the destination (timetabled or not). */ + + /** + * Get the time in ticks a vehicle will probably wait at the destination (timetabled or not). + * @return The raw wait time. + */ inline uint16_t GetWaitTime() const { return this->wait_time; } - /** Get the time in ticks a vehicle will probably take to reach the destination (timetabled or not). */ + + /** + * Get the time in ticks a vehicle will probably take to reach the destination (timetabled or not). + * @return The raw travel time. + */ inline uint16_t GetTravelTime() const { return this->travel_time; } /** @@ -206,9 +305,16 @@ public: */ inline uint16_t GetMaxSpeed() const { return this->max_speed; } - /** Set if the wait time is explicitly timetabled (unless the order is conditional). */ + /** + * Set if the wait time is explicitly timetabled (unless the order is conditional). + * @param timetabled Whether the conditional order's wait time is explicitly timetabled. + */ inline void SetWaitTimetabled(bool timetabled) { if (!this->IsType(OT_CONDITIONAL)) AssignBit(this->flags, 3, timetabled); } - /** Set if the travel time is explicitly timetabled (unless the order is conditional). */ + + /** + * Set if the travel time is explicitly timetabled (unless the order is conditional). + * @param timetabled Whether the conditional order's travel time is explicitly timetabled. + */ inline void SetTravelTimetabled(bool timetabled) { if (!this->IsType(OT_CONDITIONAL)) AssignBit(this->flags, 7, timetabled); } /** @@ -236,7 +342,10 @@ public: TileIndex GetLocation(const Vehicle *v, bool airport = false) const; - /** Checks if travel_time and wait_time apply to this order and if they are timetabled. */ + /** + * Checks if travel_time and wait_time apply to this order and if they are timetabled. + * @return \c true iff the travel and wait time are timetabled whenever possible. + */ inline bool IsCompletelyTimetabled() const { if (!this->IsTravelTimetabled() && !this->IsType(OT_CONDITIONAL)) return false; @@ -289,7 +398,10 @@ private: TimerGameTick::Ticks total_duration{}; ///< NOSAVE: Total (timetabled or not) duration of the order list. public: - /** Default constructor producing an invalid order list. */ + /** + * Default constructor producing an invalid order list. + * @param index index of the list within the order list pool + */ OrderList(OrderListID index) : OrderListPool::PoolItem<&_orderlist_pool>(index) {} /** diff --git a/src/order_cmd.cpp b/src/order_cmd.cpp index 1c182d6d61..520991c2a2 100644 --- a/src/order_cmd.cpp +++ b/src/order_cmd.cpp @@ -206,9 +206,9 @@ uint16_t Order::MapOldOrder() const } /** - * * Updates the widgets of a vehicle which contains the order-data - * + * @param v The vehicle to update the widgets for. + * @param data The arbitrary data to send to the widgets. */ void InvalidateVehicleOrder(const Vehicle *v, int data) { @@ -546,6 +546,7 @@ static inline bool OrderGoesToStation(const Vehicle *v, const Order &o) * This could kill still valid warnings (for example about void order when just * another order gets added), but assume the company will notice the problems, * when they're changing the orders. + * @param v The vehicle to remove the order news for. */ static void DeleteOrderWarnings(const Vehicle *v) { @@ -911,6 +912,7 @@ void InsertOrder(Vehicle *v, Order &&new_o, VehicleOrderID sel_ord) * Declone an order-list * @param *dst delete the orders of this vehicle * @param flags execution flags + * @return The command's costs. */ static CommandCost DecloneOrder(Vehicle *dst, DoCommandFlags flags) { @@ -1669,9 +1671,8 @@ CommandCost CmdOrderRefit(DoCommandFlags flags, VehicleID veh, VehicleOrderID or /** - * * Check the orders of a vehicle, to see if there are invalid orders and stuff - * + * @param v The vehicle to check. */ void CheckOrders(const Vehicle *v) { @@ -1871,11 +1872,10 @@ uint16_t GetServiceIntervalClamped(int interval, bool ispercent) /** * - * Check if a vehicle has any valid orders - * - * @return false if there are no valid orders + * Check if a vehicle has any valid orders. + * @param v The vehicle to check. + * @return \c false iff there are no valid orders. * @note Conditional orders are not considered valid destination orders - * */ static bool CheckForValidOrders(const Vehicle *v) { @@ -1888,6 +1888,10 @@ static bool CheckForValidOrders(const Vehicle *v) /** * Compare the variable and value based on the given comparator. + * @param occ The comparator to use. + * @param variable The first parameter of the comparison. + * @param value The second parameter. + * @return The result of the comparator on the variable and value. */ static bool OrderConditionCompare(OrderConditionComparator occ, int variable, int value) { @@ -1944,6 +1948,7 @@ VehicleOrderID ProcessConditionalOrder(const Order *order, const Vehicle *v) * @param v the vehicle to update * @param conditional_depth the depth (amount of steps) to go with conditional orders. This to prevent infinite loops. * @param pbs_look_ahead Whether we are forecasting orders for pbs reservations in advance. If true, the order indices must not be modified. + * @return \c true iff the order is suitable for reversing. */ bool UpdateOrderDest(Vehicle *v, const Order *order, int conditional_depth, bool pbs_look_ahead) { @@ -2195,6 +2200,8 @@ bool Order::CanLoadOrUnload() const * 1. it can load cargo here OR * 2a. it could leave the last station with cargo AND * 2b. it doesn't have to unload all cargo here. + * @param has_cargo Whether the vehicle has cargo. + * @return \c true iff the vehicle can leave. */ bool Order::CanLeaveWithCargo(bool has_cargo) const { diff --git a/src/order_gui.cpp b/src/order_gui.cpp index ace4c55536..9a6ad2cadd 100644 --- a/src/order_gui.cpp +++ b/src/order_gui.cpp @@ -572,6 +572,7 @@ private: /** * Handle the click on the goto button. + * @param type The variant of goto button/dropdown options. */ void OrderClick_Goto(OrderPlaceObjectState type) { @@ -609,6 +610,7 @@ private: /** * Handle the click on the service. + * @param i The optional depot action to modify the order with. */ void OrderClick_Service(std::optional i) { @@ -1473,6 +1475,8 @@ public: /** * Clones an order list from a vehicle list. If this doesn't make sense (because not all vehicles in the list have the same orders), then it displays an error. + * @param begin Begin iterator of the vehicle list. + * @param end End iterator of the vehicle list. * @return This always returns true, which indicates that the contextual action handled the mouse click. * Note that it's correct behaviour to always handle the click even though an error is displayed, * because users aren't going to expect the default action to be performed just because they overlooked that cloning doesn't make sense. diff --git a/src/osk_gui.cpp b/src/osk_gui.cpp index 7005243407..a45fd9d914 100644 --- a/src/osk_gui.cpp +++ b/src/osk_gui.cpp @@ -241,7 +241,7 @@ static void AddKey(std::unique_ptr &hor, int pad_y, int num_h } } -/** Construct the top row keys (cancel, ok, backspace). */ +/** Construct the top row keys (cancel, ok, backspace). @copydoc NWidgetFunctionType */ static std::unique_ptr MakeTopKeys() { auto hor = std::make_unique(); @@ -253,7 +253,7 @@ static std::unique_ptr MakeTopKeys() return hor; } -/** Construct the row containing the digit keys. */ +/** Construct the row containing the digit keys. @copydoc NWidgetFunctionType */ static std::unique_ptr MakeNumberKeys() { std::unique_ptr hor = std::make_unique(); @@ -265,7 +265,7 @@ static std::unique_ptr MakeNumberKeys() return hor; } -/** Construct the qwerty row keys. */ +/** Construct the qwerty row keys. @copydoc NWidgetFunctionType */ static std::unique_ptr MakeQwertyKeys() { std::unique_ptr hor = std::make_unique(); @@ -279,7 +279,7 @@ static std::unique_ptr MakeQwertyKeys() return hor; } -/** Construct the asdfg row keys. */ +/** Construct the asdfg row keys. @copydoc NWidgetFunctionType */ static std::unique_ptr MakeAsdfgKeys() { std::unique_ptr hor = std::make_unique(); @@ -292,7 +292,7 @@ static std::unique_ptr MakeAsdfgKeys() return hor; } -/** Construct the zxcvb row keys. */ +/** Construct the zxcvb row keys. @copydoc NWidgetFunctionType */ static std::unique_ptr MakeZxcvbKeys() { std::unique_ptr hor = std::make_unique(); @@ -306,7 +306,7 @@ static std::unique_ptr MakeZxcvbKeys() return hor; } -/** Construct the spacebar row keys. */ +/** Construct the spacebar row keys. @copydoc NWidgetFunctionType */ static std::unique_ptr MakeSpacebarKeys() { auto hor = std::make_unique();