Codechange: document parameters and return types

src/news_func.h

@@ -24,8 +24,10 @@ inline void AddCompanyNewsItem(EncodedString &&headline, std::unique_ptr<Company
 
 /**
  * Adds a newsitem referencing a vehicle.
- *
- * @warning The DParams may not reference the vehicle due to autoreplace stuff. See AddVehicleAdviceNewsItem for how that can be done.
+ * @param headline The actual news message.
+ * @param type The news type.
+ * @param vehicle The vehicle the advice is on.
+ * @param station The optional station associated with the news item.
  */
 inline void AddVehicleNewsItem(EncodedString &&headline, NewsType type, VehicleID vehicle, StationID station = StationID::Invalid())
 {
@@ -34,8 +36,9 @@ inline void AddVehicleNewsItem(EncodedString &&headline, NewsType type, VehicleI
 
 /**
  * Adds a vehicle-advice news item.
- *
- * @warning DParam 0 must reference the vehicle!
+ * @param advice_type The advice given.
+ * @param headline The actual news message.
+ * @param vehicle The vehicle the advice is on.
  */
 inline void AddVehicleAdviceNewsItem(AdviceType advice_type, EncodedString &&headline, VehicleID vehicle)
 {

src/news_gui.cpp

@@ -692,7 +692,10 @@ private:
 
 /* static */ int NewsWindow::duration = 0; // Instance creation.
 
-/** Open up an own newspaper window for the news item */
+/**
+ * Open up an own newspaper window for the news item.
+ * @param ni Iterator to the news message to show.
+ */
 static void ShowNewspaper(const NewsItem *ni)
 {
 	SoundFx sound = _news_type_data[to_underlying(ni->type)].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<NewsItem>::iterator DeleteNewsItem(std::list<NewsItem>::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 <size_t Tmin = 0, class Tpredicate>
 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));

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)
 	{

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. */

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<LoadFilter> lf = nullptr)
 {

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<OrderLoadType>(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<OrderUnloadType>(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<OrderNonStopFlags>(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<OrderStopLocation>(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<OrderDepotTypeFlags>(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<OrderDepotActionFlags>(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<OrderConditionVariable>(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<OrderConditionComparator>(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) {}
 
 	/**

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
 {

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<OrderDepotAction> 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.

src/osk_gui.cpp

@@ -241,7 +241,7 @@ static void AddKey(std::unique_ptr<NWidgetHorizontal> &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<NWidgetBase> MakeTopKeys()
 {
 	auto hor = std::make_unique<NWidgetHorizontal>();
@@ -253,7 +253,7 @@ static std::unique_ptr<NWidgetBase> MakeTopKeys()
 	return hor;
 }
 
-/** Construct the row containing the digit keys. */
+/** Construct the row containing the digit keys. @copydoc NWidgetFunctionType */
 static std::unique_ptr<NWidgetBase> MakeNumberKeys()
 {
 	std::unique_ptr<NWidgetHorizontal> hor = std::make_unique<NWidgetHorizontalLTR>();
@@ -265,7 +265,7 @@ static std::unique_ptr<NWidgetBase> MakeNumberKeys()
 	return hor;
 }
 
-/** Construct the qwerty row keys. */
+/** Construct the qwerty row keys. @copydoc NWidgetFunctionType */
 static std::unique_ptr<NWidgetBase> MakeQwertyKeys()
 {
 	std::unique_ptr<NWidgetHorizontal> hor = std::make_unique<NWidgetHorizontalLTR>();
@@ -279,7 +279,7 @@ static std::unique_ptr<NWidgetBase> MakeQwertyKeys()
 	return hor;
 }
 
-/** Construct the asdfg row keys. */
+/** Construct the asdfg row keys. @copydoc NWidgetFunctionType */
 static std::unique_ptr<NWidgetBase> MakeAsdfgKeys()
 {
 	std::unique_ptr<NWidgetHorizontal> hor = std::make_unique<NWidgetHorizontalLTR>();
@@ -292,7 +292,7 @@ static std::unique_ptr<NWidgetBase> MakeAsdfgKeys()
 	return hor;
 }
 
-/** Construct the zxcvb row keys. */
+/** Construct the zxcvb row keys. @copydoc NWidgetFunctionType */
 static std::unique_ptr<NWidgetBase> MakeZxcvbKeys()
 {
 	std::unique_ptr<NWidgetHorizontal> hor = std::make_unique<NWidgetHorizontalLTR>();
@@ -306,7 +306,7 @@ static std::unique_ptr<NWidgetBase> MakeZxcvbKeys()
 	return hor;
 }
 
-/** Construct the spacebar row keys. */
+/** Construct the spacebar row keys. @copydoc NWidgetFunctionType */
 static std::unique_ptr<NWidgetBase> MakeSpacebarKeys()
 {
 	auto hor = std::make_unique<NWidgetHorizontal>();