Codechange: document a number of functions and variables

src/aircraft_cmd.cpp

@@ -93,6 +93,7 @@ static const SpriteID _aircraft_sprite[] = {
 	0x0EBD, 0x0EC5
 };
 
+/** @copydoc IsValidImageIndex */
 template <>
 bool IsValidImageIndex<VEH_AIRCRAFT>(uint8_t image_index)
 {

src/base_media_base.h

@@ -51,7 +51,8 @@ struct BaseSet {
 	/** Ensure the destructor of the sub classes are called as well. */
 	virtual ~BaseSet() = default;
 
-	typedef std::unordered_map<std::string, std::string, StringHash, std::equal_to<>> TranslatedStrings;
+	/** Mapping of translations: language -> string. */
+	using TranslatedStrings = std::unordered_map<std::string, std::string, StringHash, std::equal_to<>>;
 
 	/** Number of files in this set */
 	static constexpr size_t NUM_FILES = BaseSetTraits<T>::num_files;
@@ -96,6 +97,11 @@ struct BaseSet {
 	const IniItem *GetMandatoryItem(std::string_view full_filename, const IniGroup &group, std::string_view name) const;
 
 	bool FillSetDetails(const IniFile &ini, const std::string &path, const std::string &full_filename, bool allow_empty_filename = true);
+
+	/**
+	 * Copy settings from the given set into this set when they are compatible.
+	 * @param src The location to copy settings from.
+	 */
 	void CopyCompatibleConfig([[maybe_unused]] const T &src) {}
 
 	/**

src/base_media_graphics.h

@@ -31,10 +31,11 @@ enum BlitterType : uint8_t {
 
 struct GRFConfig;
 
+/** Instantiation of BaseSetTraits for a GraphicSet. */
 template <> struct BaseSetTraits<struct GraphicsSet> {
-	static constexpr size_t num_files = MAX_GFT;
-	static constexpr bool search_in_tars = true;
-	static constexpr std::string_view set_type = "graphics";
+	static constexpr size_t num_files = MAX_GFT; ///< Number of files in a graphics set.
+	static constexpr bool search_in_tars = true; ///< Graphics can be in a tar file.
+	static constexpr std::string_view set_type = "graphics"; ///< The type of set.
 };
 
 /** All data of a graphics set. */

src/base_media_music.h

@@ -43,10 +43,11 @@ struct MusicSongInfo {
 	bool loop; ///< song should play in a tight loop if possible, never ending
 };
 
+/** Instantiation of BaseSetTraits for a MusicSet. */
 template <> struct BaseSetTraits<struct MusicSet> {
-	static constexpr size_t num_files = NUM_SONGS_AVAILABLE;
-	static constexpr bool search_in_tars = false;
-	static constexpr std::string_view set_type = "music";
+	static constexpr size_t num_files = NUM_SONGS_AVAILABLE; ///< Maximum number of files in a music set.
+	static constexpr bool search_in_tars = false; ///< Music cannot be in a tar file.
+	static constexpr std::string_view set_type = "music"; ///< The type of set.
 };
 
 /** All data of a music set. */

src/base_media_sounds.h

@@ -12,10 +12,11 @@
 
 #include "base_media_base.h"
 
+/** Instantiation of BaseSetTraits for a SoundsSet. */
 template <> struct BaseSetTraits<struct SoundsSet> {
-	static constexpr size_t num_files = 1;
-	static constexpr bool search_in_tars = true;
-	static constexpr std::string_view set_type = "sounds";
+	static constexpr size_t num_files = 1; ///< Number of files in a sound set.
+	static constexpr bool search_in_tars = true; ///< Sounds can be in a tar file.
+	static constexpr std::string_view set_type = "sounds"; ///< The type of set.
 };
 
 /** All data of a sounds set. */

src/base_station_base.h

@@ -339,7 +339,9 @@ struct SpecializedStation : public BaseStation {
  * @return Speclist of custom spec type.
  */
 template <class T> std::vector<SpecMapping<T>> &GetStationSpecList(BaseStation *bst);
+/** @copydoc GetStationSpecList */
 template <> inline std::vector<SpecMapping<StationSpec>> &GetStationSpecList<StationSpec>(BaseStation *bst) { return bst->speclist; }
+/** @copydoc GetStationSpecList */
 template <> inline std::vector<SpecMapping<RoadStopSpec>> &GetStationSpecList<RoadStopSpec>(BaseStation *bst) { return bst->roadstop_speclist; }
 
 #endif /* BASE_STATION_BASE_H */

src/cargoaction.h

@@ -24,6 +24,11 @@ protected:
 	uint Preprocess(CargoPacket *cp);
 	bool Postprocess(CargoPacket *cp, uint remove);
 public:
+	/**
+	 * Create the removal.
+	 * @param source The source of the cargo.
+	 * @param max_move The maximum amount of cargo to be removed.
+	 */
 	CargoRemoval(Tsource *source, uint max_move) : source(source), max_move(max_move) {}
 
 	/**
@@ -42,6 +47,14 @@ protected:
 	CargoPayment *payment; ///< Payment object where payments will be registered.
 	CargoType cargo; ///< The cargo type of the cargo.
 public:
+	/**
+	 * Create the delivery.
+	 * @param source The source of the cargo.
+	 * @param max_move The maximum amount of cargo to be moved.
+	 * @param cargo The type of cargo.
+	 * @param payment The payment for the delivery.
+	 * @param current_tile The tile the data is being delivered from.
+	 */
 	CargoDelivery(VehicleCargoList *source, uint max_move, CargoType cargo, CargoPayment *payment, TileIndex current_tile) :
 			CargoRemoval<VehicleCargoList>(source, max_move), current_tile(current_tile), payment(payment), cargo(cargo) {}
 	bool operator()(CargoPacket *cp);
@@ -60,6 +73,12 @@ protected:
 	uint max_move;      ///< Maximum amount of cargo to be moved with this action.
 	CargoPacket *Preprocess(CargoPacket *cp);
 public:
+	/**
+	 * Create the movement.
+	 * @param source The source of the cargo.
+	 * @param destination The destination of the cargo.
+	 * @param max_move The maximum amount of cargo to be moved.
+	 */
 	CargoMovement(Tsource *source, Tdest *destination, uint max_move) : source(source), destination(destination), max_move(max_move) {}
 
 	/**
@@ -120,10 +139,19 @@ public:
 template <class Tlist>
 class CargoReroute : public CargoMovement<Tlist, Tlist> {
 protected:
-	StationID avoid;
-	StationID avoid2;
-	const GoodsEntry *ge;
+	StationID avoid; ///< First station to avoid during rerouting.
+	StationID avoid2; ///< Second station to avoid during rerouting, could be StationID::Invalid().
+	const GoodsEntry *ge; ///< Goods that are to be rerouted.
 public:
+	/**
+	 * Create the movement.
+	 * @param source The source of the cargo.
+	 * @param dest The destination of the cargo.
+	 * @param max_move The maximum amount of cargo to be moved.
+	 * @param avoid First station to avoid.
+	 * @param avoid2 Optional second station to avoid (use StationID::Invalid()).
+	 * @param ge The goods to reroute.
+	 */
 	CargoReroute(Tlist *source, Tlist *dest, uint max_move, StationID avoid, StationID avoid2, const GoodsEntry *ge) :
 			CargoMovement<Tlist, Tlist>(source, dest, max_move), avoid(avoid), avoid2(avoid2), ge(ge) {}
 };

src/command_type.h

@@ -452,17 +452,17 @@ enum class CommandPauseLevel : uint8_t {
 template <typename T> struct CommandFunctionTraitHelper;
 template <typename... Targs>
 struct CommandFunctionTraitHelper<CommandCost(*)(DoCommandFlags, Targs...)> {
-	using Args = std::tuple<std::decay_t<Targs>...>;
-	using RetTypes = void;
-	using CbArgs = Args;
-	using CbProcType = void(*)(Commands, const CommandCost &);
+	using Args = std::tuple<std::decay_t<Targs>...>; ///< \c std::tuple with argument types for the command.
+	using RetTypes = void; ///< The return type of the command.
+	using CbArgs = Args; ///< The argument type of the callback.
+	using CbProcType = void(*)(Commands, const CommandCost &); ///< The function prototype of the callback.
 };
 template <template <typename...> typename Tret, typename... Tretargs, typename... Targs>
 struct CommandFunctionTraitHelper<Tret<CommandCost, Tretargs...>(*)(DoCommandFlags, Targs...)> {
-	using Args = std::tuple<std::decay_t<Targs>...>;
-	using RetTypes = std::tuple<std::decay_t<Tretargs>...>;
-	using CbArgs = std::tuple<std::decay_t<Tretargs>..., std::decay_t<Targs>...>;
-	using CbProcType = void(*)(Commands, const CommandCost &, Tretargs...);
+	using Args = std::tuple<std::decay_t<Targs>...>; ///< \c std::tuple with argument types for the command.
+	using RetTypes = std::tuple<std::decay_t<Tretargs>...>; ///< \c std::tuple with return types of the command.
+	using CbArgs = std::tuple<std::decay_t<Tretargs>..., std::decay_t<Targs>...>; ///< \c std::tuple with return and argument types for the callback.
+	using CbProcType = void(*)(Commands, const CommandCost &, Tretargs...); ///< The function prototype of the callback.
 };
 
 /** Defines the traits of a command. */

src/gfxinit.cpp

@@ -393,6 +393,10 @@ GRFConfig &GraphicsSet::GetOrCreateExtraConfig() const
 	return *this->extra_cfg;
 }
 
+/**
+ * Checks whether this set has configuration options.
+ * @return \c true iff there are parameters for this graphics set.
+ */
 bool GraphicsSet::IsConfigurable() const
 {
 	const GRFConfig &cfg = this->GetOrCreateExtraConfig();
@@ -474,6 +478,7 @@ template <>
 	return _graphics_file_names;
 }
 
+/** @copydoc BaseMedia::DetermineBestSet */
 template <>
 /* static */ bool BaseMedia<GraphicsSet>::DetermineBestSet()
 {
@@ -507,6 +512,7 @@ template <>
 	return BaseMedia<GraphicsSet>::used_set != nullptr;
 }
 
+/** @copydoc BaseMedia::GetExtension */
 template <>
 /* static */ std::string_view BaseMedia<GraphicsSet>::GetExtension()
 {

src/music.cpp

@@ -84,12 +84,14 @@ template <>
 	return _music_file_names;
 }
 
+/** @copydoc BaseMedia::GetExtension */
 template <>
 /* static */ std::string_view BaseMedia<MusicSet>::GetExtension()
 {
 	return ".obm"; // OpenTTD Base Music
 }
 
+/** @copydoc BaseMedia::DetermineBestSet */
 template <>
 /* static */ bool BaseMedia<MusicSet>::DetermineBestSet()
 {

src/network/network_command.cpp

@@ -126,7 +126,7 @@ bool IsNetworkRegisteredCallback(CommandCallback *callback)
 template <typename T> struct CallbackArgsHelper;
 template <typename... Targs>
 struct CallbackArgsHelper<void(*const)(Commands, const CommandCost &, Targs...)> {
-	using Args = std::tuple<std::decay_t<Targs>...>;
+	using Args = std::tuple<std::decay_t<Targs>...>; ///< \c std::tuple with argument types for the callback.
 };
 
 

src/newgrf_spritegroup.h

@@ -46,6 +46,10 @@ extern SpriteGroupPool _spritegroup_pool;
 /** Common wrapper for all the different sprite group types. */
 struct SpriteGroup : SpriteGroupPool::PoolItem<&_spritegroup_pool> {
 protected:
+	/**
+	 * Create the SpriteGroup.
+	 * @param index Index of the sprite group within the pool.
+	 */
 	SpriteGroup(SpriteGroupID index) : SpriteGroupPool::PoolItem<&_spritegroup_pool>(index) {}
 	/**
 	 * Resolves a callback or rerandomisation callback to a NewGRF.
@@ -69,6 +73,10 @@ public:
  */
 template <class T>
 struct SpecializedSpriteGroup : public SpriteGroup {
+	/**
+	 * Create the SpecializedSpriteGroup.
+	 * @param index Index of the sprite group within the pool.
+	 */
 	inline SpecializedSpriteGroup(SpriteGroupID index) : SpriteGroup(index) {}
 
 	/**
@@ -86,6 +94,10 @@ struct SpecializedSpriteGroup : public SpriteGroup {
 
 /** 'Real' sprite groups contain a list of other result or callback sprite groups. */
 struct RealSpriteGroup : SpecializedSpriteGroup<RealSpriteGroup> {
+	/**
+	 * Create the RealSpriteGroup.
+	 * @param index Index of the sprite group within the pool.
+	 */
 	RealSpriteGroup(SpriteGroupID index) : SpecializedSpriteGroup<RealSpriteGroup>(index) {}
 
 	/* Loaded = in motion, loading = not moving

src/picker_gui.h

@@ -218,10 +218,32 @@ public:
 template <typename T>
 class PickerCallbacksNewGRFClass : public PickerCallbacks {
 public:
+	/**
+	 * Create the callback instance.
+	 * @param ini_group The group in the configuration file to save/load state to/from.
+	 */
 	explicit PickerCallbacksNewGRFClass(const std::string &ini_group) : PickerCallbacks(ini_group) {}
 
+	/**
+	 * Casts the given index to the right type.
+	 * @param cls_id The index to cast.
+	 * @return The index with the right type.
+	 */
 	inline typename T::index_type GetClassIndex(int cls_id) const { return static_cast<typename T::index_type>(cls_id); }
+
+	/**
+	 * Get the class with the given index.
+	 * @param cls_id The index of the class to get.
+	 * @return The class instance.
+	 */
 	inline const T *GetClass(int cls_id) const { return T::Get(this->GetClassIndex(cls_id)); }
+
+	/**
+	 * Get the spec of an object within a class.
+	 * @param cls_id The index of the class.
+	 * @param id The index of the spec within the class.
+	 * @return The spec.
+	 */
 	inline const typename T::spec_type *GetSpec(int cls_id, int id) const { return this->GetClass(cls_id)->GetSpec(id); }
 
 	bool HasClassChoice() const override { return T::GetUIClassCount() > 1; }
@@ -229,12 +251,25 @@ public:
 	int GetClassCount() const override { return T::GetClassCount(); }
 	int GetTypeCount(int cls_id) const override { return this->GetClass(cls_id)->GetSpecCount(); }
 
+	/**
+	 * Get the PickerItem for the given spec.
+	 * @param spec The spec to get the picker item to.
+	 * @param cls_id Optional index of the class, in case \c spec is \c nullptr.
+	 * @param id Optional index of the spec within the class, in case \c spec is \c nullptr.
+	 * @return The PickerItem with metadata.
+	 */
 	PickerItem GetPickerItem(const typename T::spec_type *spec, int cls_id = -1, int id = -1) const
 	{
 		if (spec == nullptr) return {0, 0, cls_id, id};
 		return {spec->grf_prop.grfid, spec->grf_prop.local_id, spec->class_index.base(), spec->index};
 	}
 
+	/**
+	 * Get the PickerItem for the given index with the class.
+	 * @param cls_id The index of the class.
+	 * @param id The index of the spec within the class.
+	 * @return The PickerItem with metadata.
+	 */
 	PickerItem GetPickerItem(int cls_id, int id) const override
 	{
 		return GetPickerItem(GetClass(cls_id)->GetSpec(id), cls_id, id);

src/provider_manager.h

@@ -53,11 +53,25 @@ public:
 template <typename T>
 class BaseProvider {
 public:
+	/**
+	 * Create the provider.
+	 * @param name The name of the provider.
+	 * @param description A description of the provider.
+	 */
 	constexpr BaseProvider(std::string_view name, std::string_view description) : name(name), description(description) {}
 	/** Ensure the destructor of the sub classes are called as well. */
 	virtual ~BaseProvider() = default;
 
+	/**
+	 * Get the name of this provider.
+	 * @return Our name.
+	 */
 	inline std::string_view GetName() const { return this->name; }
+
+	/**
+	 * Get a description of this provider.
+	 * @return The description.
+	 */
 	inline std::string_view GetDescription() const { return this->description; }
 
 	/**
@@ -75,15 +89,25 @@ public:
 	};
 
 protected:
-	const std::string_view name;
-	const std::string_view description;
+	const std::string_view name; ///< The name of the provider.
+	const std::string_view description; ///< A description of the provider.
 };
 
 template <typename T>
 class PriorityBaseProvider : public BaseProvider<T> {
 public:
+	/**
+	 * Create the provider.
+	 * @param name The name of the provider.
+	 * @param description A description of the provider.
+	 * @param priority The priority number to sort all providers by.
+	 */
 	constexpr PriorityBaseProvider(std::string_view name, std::string_view description, int priority) : BaseProvider<T>(name, description), priority(priority) {}
 
+	/**
+	 * Get the priority of this provider.
+	 * @return The priority.
+	 */
 	inline int GetPriority() const { return this->priority; }
 
 	/**
@@ -101,7 +125,7 @@ public:
 	};
 
 protected:
-	const int priority;
+	const int priority; ///< The priority of this provider.
 };
 
 #endif /* PROVIDER_MANAGER_H */

src/roadveh_cmd.cpp

@@ -65,6 +65,7 @@ static const uint16_t _roadveh_full_adder[] = {
 };
 static_assert(lengthof(_roadveh_images) == lengthof(_roadveh_full_adder));
 
+/** @copydoc IsValidImageIndex */
 template <>
 bool IsValidImageIndex<VEH_ROAD>(uint8_t image_index)
 {

src/ship_cmd.cpp

@@ -66,6 +66,7 @@ WaterClass GetEffectiveWaterClass(TileIndex tile)
 
 static const uint16_t _ship_sprites[] = {0x0E5D, 0x0E55, 0x0E65, 0x0E6D};
 
+/** @copydoc IsValidImageIndex */
 template <>
 bool IsValidImageIndex<VEH_SHIP>(uint8_t image_index)
 {

src/sound.cpp

@@ -273,12 +273,14 @@ template <>
 	return _sound_file_names;
 }
 
+/** @copydoc BaseMedia::GetExtension */
 template <>
 /* static */ std::string_view BaseMedia<SoundsSet>::GetExtension()
 {
 	return ".obs"; // OpenTTD Base Sounds
 }
 
+/** @copydoc BaseMedia::DetermineBestSet */
 template <>
 /* static */ bool BaseMedia<SoundsSet>::DetermineBestSet()
 {

src/timer/timer_game_common.h

@@ -30,15 +30,17 @@
 template <class T>
 class TimerGame {
 public:
-	/** The type to store our dates in. */
+	/** The tag for making Date StrongType. */
 	template <class ST> struct DateTag;
+	/** The type to store our dates in. */
 	using Date = StrongType::Typedef<int32_t, DateTag<T>, StrongType::Compare, StrongType::Integer>;
 
 	/** The fraction of a date we're in, i.e. the number of ticks since the last date changeover. */
 	using DateFract = uint16_t;
 
-	/** Type for the year, note: 0 based, i.e. starts at the year 0. */
+	/** The tag for making Year StrongType. */
 	template <class ST> struct YearTag;
+	/** Type for the year, note: 0 based, i.e. starts at the year 0. */
 	using Year = StrongType::Typedef<int32_t, struct YearTag<T>, StrongType::Compare, StrongType::Integer>;
 	/** Type for the month, note: 0 based, i.e. 0 = January, 11 = December. */
 	using Month = uint8_t;

src/train_cmd.cpp

@@ -53,6 +53,7 @@ static void CheckNextTrainTile(Train *v);
 static const uint8_t _vehicle_initial_x_fract[4] = {10, 8, 4,  8};
 static const uint8_t _vehicle_initial_y_fract[4] = { 8, 4, 8, 10};
 
+/** @copydoc IsValidImageIndex */
 template <>
 bool IsValidImageIndex<VEH_TRAIN>(uint8_t image_index)
 {