Codechange: Make documentation comments for some types recognised by doxygen.

src/bridge.h

@@ -18,7 +18,7 @@
 static const uint MAX_BRIDGES = 13; ///< Maximal number of available bridge specs.
 constexpr uint SPRITES_PER_BRIDGE_PIECE = 32; ///< Number of sprites there are per bridge piece.
 
-/* Container for Bridge pillar flags for each axis of each bridge middle piece. */
+/** Container for Bridge pillar flags for each axis of each bridge middle piece. */
 using BridgeMiddlePillarFlags = std::array<std::array<BridgePillarFlags, AXIS_END>, NUM_BRIDGE_MIDDLE_PIECES>;
 
 /**

src/cargopacket.h

@@ -40,7 +40,7 @@ extern SaveLoadTable GetCargoPacketDesc();
  */
 struct CargoPacket : CargoPacketPool::PoolItem<&_cargopacket_pool> {
 private:
-	/* A mathematical vector from (0,0). */
+	/** A mathematical vector from (0,0). */
 	struct Vector {
 		int16_t x;
 		int16_t y;

src/cargotype.h

@@ -174,9 +174,7 @@ struct CargoSpec {
 		void ValidateIndex() { while (this->index < CargoSpec::GetArraySize() && !(CargoSpec::Get(this->index)->IsValid())) this->index++; }
 	};
 
-	/*
-	 * Iterable ensemble of all valid CargoSpec
-	 */
+	/** Iterable ensemble of all valid CargoSpec. */
 	struct IterateWrapper {
 		size_t from;
 		IterateWrapper(size_t from = 0) : from(from) {}

src/dropdown_common_type.h

@@ -299,7 +299,6 @@ public:
 	bool Selectable() const override { return false; }
 };
 
-/* Commonly used drop down list items. */
 using DropDownListDividerItem = DropDownDivider<DropDownListItem>;
 using DropDownListStringItem = DropDownString<DropDownListItem>;
 using DropDownListIconItem = DropDownIcon<DropDownString<DropDownListItem>>;

src/gfx_layout.h

@@ -257,7 +257,7 @@ class Layouter : public std::vector<const ParagraphLayouter::Line *> {
 public:
 	/** Item in the linecache */
 	struct LineCacheItem {
-		/* Due to the type of data in the buffer differing depending on the Layouter, we need to pass our own deleter routine. */
+		/** Due to the type of data in the buffer differing depending on the Layouter, we need to pass our own deleter routine. */
 		using Buffer = std::unique_ptr<void, void(*)(void *)>;
 		/* Stuff that cannot be freed until the ParagraphLayout is freed */
 		Buffer buffer{nullptr, [](void *){}}; ///< Accessed by our ParagraphLayout::nextLine.

src/map_func.h

@@ -215,9 +215,7 @@ private:
 		TileIndex index;
 	};
 
-	/*
-	 * Iterable ensemble of all Tiles
-	 */
+	/** Iterable ensemble of all %Tiles. */
 	struct IterateWrapper {
 		Iterator begin() { return Iterator(TileIndex{}); }
 		Iterator end() { return Iterator(TileIndex{Map::Size()}); }

src/misc/hashtable.hpp

@@ -12,7 +12,7 @@
 
 template <class TItem>
 struct HashTableSlot {
-	typedef typename TItem::Key Key; // make Titem::Key a property of HashTable
+	typedef typename TItem::Key Key; ///< Make Titem::Key a property of HashTable.
 
 	TItem *first_item = nullptr;
 
@@ -148,7 +148,7 @@ struct HashTableSlot {
 template <class Titem, int Thash_bits_>
 class HashTable {
 public:
-	typedef typename Titem::Key Tkey; // make Titem::Key a property of HashTable
+	typedef typename Titem::Key Tkey; ///< Make Titem::Key a property of HashTable.
 	static constexpr int HASH_BITS = Thash_bits_; ///< Publish num of hash bits.
 	static constexpr int CAPACITY = 1 << HASH_BITS; ///< And num of slots 2^bits.
 

src/newgrf_spritegroup.h

@@ -43,7 +43,7 @@ using SpriteGroupID = PoolID<uint32_t, struct SpriteGroupIDTag, 1U << 30, 0xFFFF
 using SpriteGroupPool = Pool<SpriteGroup, SpriteGroupID, 1024, PoolType::Data>;
 extern SpriteGroupPool _spritegroup_pool;
 
-/* Common wrapper for all the different sprite group types */
+/** Common wrapper for all the different sprite group types. */
 struct SpriteGroup : SpriteGroupPool::PoolItem<&_spritegroup_pool> {
 protected:
 	SpriteGroup(SpriteGroupID index) : SpriteGroupPool::PoolItem<&_spritegroup_pool>(index) {}
@@ -83,8 +83,7 @@ struct SpecializedSpriteGroup : public SpriteGroup {
 };
 
 
-/* 'Real' sprite groups contain a list of other result or callback sprite
- * groups. */
+/** 'Real' sprite groups contain a list of other result or callback sprite groups. */
 struct RealSpriteGroup : SpecializedSpriteGroup<RealSpriteGroup> {
 	RealSpriteGroup(SpriteGroupID index) : SpecializedSpriteGroup<RealSpriteGroup>(index) {}
 
@@ -220,8 +219,7 @@ protected:
 };
 
 
-/* This contains a callback result. A failed callback has a value of
- * CALLBACK_FAILED */
+/** This contains a callback result. A failed callback has a value of %CALLBACK_FAILED. */
 struct CallbackResultSpriteGroup : SpecializedSpriteGroup<CallbackResultSpriteGroup> {
 	/**
 	 * Creates a spritegroup representing a callback result
@@ -237,8 +235,7 @@ protected:
 };
 
 
-/* A result sprite group returns the first SpriteID and the number of
- * sprites in the set */
+/** A result sprite group returns the first SpriteID and the number of sprites in the set. */
 struct ResultSpriteGroup : SpecializedSpriteGroup<ResultSpriteGroup> {
 	/**
 	 * Creates a spritegroup representing a sprite number result.

src/order_base.h

@@ -26,7 +26,8 @@ extern OrderListPool _orderlist_pool;
 template <typename, typename>
 class EndianBufferWriter;
 
-/* If you change this, keep in mind that it is saved on 3 places:
+/**
+ * If you change this, keep in mind that it is also saved in 2 other places:
  * - Load_ORDR, all the global orders
  * - Vehicle -> current_order
  */

src/pathfinder/yapf/yapf_costrail.hpp

@@ -28,7 +28,7 @@ public:
 
 protected:
 
-	/* Structure used inside PfCalcCost() to keep basic tile information. */
+	/** Structure used inside PfCalcCost() to keep basic tile information. */
 	struct TILE {
 		TileIndex   tile;
 		Trackdir    td;

src/pathfinder/yapf/yapf_river_builder.cpp

@@ -18,7 +18,7 @@
 /* River builder pathfinder node. */
 struct YapfRiverBuilderNode : CYapfNodeT<CYapfNodeKeyTrackDir, YapfRiverBuilderNode> {};
 
-/* River builder pathfinder node list. */
+/** River builder pathfinder node list. */
 using RiverBuilderNodeList = NodeList<YapfRiverBuilderNode, 8, 10>;
 
 /* We don't need a follower but YAPF requires one. */
@@ -29,7 +29,7 @@ struct DummyVehicle : Vehicle {};
 
 class YapfRiverBuilder;
 
-/* Types struct required for YAPF components. */
+/** Types struct required for YAPF components. */
 struct RiverBuilderTypes {
 	using Tpf = YapfRiverBuilder;
 	using TrackFollower = RiverBuilderFollower;
@@ -37,7 +37,7 @@ struct RiverBuilderTypes {
 	using VehicleType = DummyVehicle;
 };
 
-/* River builder pathfinder implementation. */
+/** River builder pathfinder implementation. */
 class YapfRiverBuilder
 	: public CYapfBaseT<RiverBuilderTypes>
 	, public CYapfSegmentCostCacheNoneT<RiverBuilderTypes>

src/pathfinder/yapf/yapf_ship_regions.cpp

@@ -80,7 +80,7 @@ struct WaterRegionFollower : public CFollowTrackWater {};
 
 class YapfShipRegions;
 
-/* Types struct required for YAPF internals. */
+/** Types struct required for YAPF internals. */
 struct WaterRegionTypes {
 	using Tpf = YapfShipRegions;
 	using TrackFollower = WaterRegionFollower;

src/saveload/company_sl.cpp

@@ -269,7 +269,7 @@ void AfterLoadCompanyStats()
 	}
 }
 
-/* We do need to read this single value, as the bigger it gets, the more data is stored */
+/** We do need to read this single value, as the bigger it gets, the more data is stored. */
 struct CompanyOldAI {
 	uint8_t num_build_rec;
 };

src/saveload/misc_sl.cpp

@@ -114,8 +114,10 @@ static const SaveLoad _date_check_desc[] = {
 	SLEG_CONDVAR("date", _load_check_data.current_date,  SLE_INT32,                  SLV_31, SL_MAX_VERSION),
 };
 
-/* Save load date related variables as well as persistent tick counters
- * XXX: currently some unrelated stuff is just put here */
+/**
+ * Save load date related variables as well as persistent tick counters.
+ * @note currently some unrelated stuff is just put here.
+ */
 struct DATEChunkHandler : ChunkHandler {
 	DATEChunkHandler() : ChunkHandler('DATE', CH_TABLE) {}
 

src/saveload/water_regions_sl.cpp

@@ -15,7 +15,7 @@
 
 extern void SlSkipArray();
 
-/* Water Region savegame data is no longer used, but still needed for old savegames to load without errors. */
+/** Water Region savegame data is no longer used, but still needed for old savegames to load without errors. */
 struct WaterRegionChunkHandler : ChunkHandler {
 	WaterRegionChunkHandler() : ChunkHandler('WRGN', CH_READONLY)
 	{}

src/sortlist_type.h

@@ -77,8 +77,10 @@ protected:
 	uint8_t filter_type;                        ///< what criteria to filter on
 	uint16_t resort_timer;                      ///< resort list after a given amount of ticks if set
 
-	/* If sort parameters are used then params must be a reference, however if not then params cannot be a reference as
-	 * it will not be able to reference anything. */
+	/**
+	 * If sort parameters are used then params must be a reference,
+	 * however if not then params cannot be a reference as it will not be able to reference anything.
+	 */
 	using SortParameterReference = std::conditional_t<std::is_same_v<P, std::nullptr_t>, P, P&>;
 	const SortParameterReference params; ///< @copydoc SortParameterReference
 

src/sound/xaudio2_s.cpp

@@ -34,7 +34,7 @@ using Microsoft::WRL::ComPtr;
 #include "../os/windows/win32.h"
 #include "../safeguards.h"
 
-/* Definition of the "XAudio2Create" call used to initialise XAudio2 */
+/** Definition of the "XAudio2Create" call used to initialise XAudio2. */
 typedef HRESULT(__stdcall *API_XAudio2Create)(_Outptr_ IXAudio2 **ppXAudio2, UINT32 Flags, XAUDIO2_PROCESSOR XAudio2Processor);
 
 static FSoundDriver_XAudio2 iFSoundDriver_XAudio2;

src/station_gui.cpp

@@ -261,7 +261,7 @@ typedef GUIList<const Station*, const CargoTypes &> GUIStationList;
 class CompanyStationsWindow : public Window
 {
 protected:
-	/* Runtime saved values */
+	/** Runtime saved values. */
 	struct FilterState {
 		Listing last_sorting;
 		StationFacilities facilities; ///< types of stations of interest

src/town_gui.cpp

@@ -343,7 +343,7 @@ static void ShowTownAuthorityWindow(uint town)
 }
 
 
-/* Town view window. */
+/** Town view window. */
 struct TownViewWindow : Window {
 private:
 	Town *town = nullptr; ///< Town displayed by the window.

src/viewport_gui.cpp

@@ -50,6 +50,7 @@ static constexpr std::initializer_list<NWidgetPart> _nested_extra_viewport_widge
 	EndContainer(),
 };
 
+/** Extra viewport window. */
 class ExtraViewportWindow : public Window {
 public:
 	ExtraViewportWindow(WindowDesc &desc, int window_number, TileIndex tile) : Window(desc)