diff --git a/src/bridge.h b/src/bridge.h
index d5ee631c8d..30ca2fe0a1 100644
--- a/src/bridge.h
+++ b/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>;
 
 /**
diff --git a/src/cargopacket.h b/src/cargopacket.h
index f625a7cf02..887b31c691 100644
--- a/src/cargopacket.h
+++ b/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;
diff --git a/src/cargotype.h b/src/cargotype.h
index 1fb737849e..c9e69c0416 100644
--- a/src/cargotype.h
+++ b/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) {}
diff --git a/src/dropdown_common_type.h b/src/dropdown_common_type.h
index 98939adc21..6efd5b7277 100644
--- a/src/dropdown_common_type.h
+++ b/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>>;
diff --git a/src/gfx_layout.h b/src/gfx_layout.h
index c140a1f96b..c58d041f48 100644
--- a/src/gfx_layout.h
+++ b/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.
diff --git a/src/map_func.h b/src/map_func.h
index 54160989a9..d670670fc6 100644
--- a/src/map_func.h
+++ b/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()}); }
diff --git a/src/misc/hashtable.hpp b/src/misc/hashtable.hpp
index f44cfbd852..18720d53a8 100644
--- a/src/misc/hashtable.hpp
+++ b/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.
 
diff --git a/src/newgrf_spritegroup.h b/src/newgrf_spritegroup.h
index 3de0d70927..9452d42b67 100644
--- a/src/newgrf_spritegroup.h
+++ b/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.
diff --git a/src/order_base.h b/src/order_base.h
index 14d2ebe043..2fe25a2c3a 100644
--- a/src/order_base.h
+++ b/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
  */
diff --git a/src/pathfinder/yapf/yapf_costrail.hpp b/src/pathfinder/yapf/yapf_costrail.hpp
index 270c523cab..2ecf6052a0 100644
--- a/src/pathfinder/yapf/yapf_costrail.hpp
+++ b/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;
diff --git a/src/pathfinder/yapf/yapf_river_builder.cpp b/src/pathfinder/yapf/yapf_river_builder.cpp
index 05355c9c95..8e59b28096 100644
--- a/src/pathfinder/yapf/yapf_river_builder.cpp
+++ b/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>
diff --git a/src/pathfinder/yapf/yapf_ship_regions.cpp b/src/pathfinder/yapf/yapf_ship_regions.cpp
index c0a2c282f8..66fc381938 100644
--- a/src/pathfinder/yapf/yapf_ship_regions.cpp
+++ b/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;
diff --git a/src/saveload/company_sl.cpp b/src/saveload/company_sl.cpp
index a6c2a77c23..ff2bc4ccb8 100644
--- a/src/saveload/company_sl.cpp
+++ b/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;
 };
diff --git a/src/saveload/misc_sl.cpp b/src/saveload/misc_sl.cpp
index c68577a027..b8541a62bc 100644
--- a/src/saveload/misc_sl.cpp
+++ b/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) {}
 
diff --git a/src/saveload/water_regions_sl.cpp b/src/saveload/water_regions_sl.cpp
index e24553cb7b..0cc88d9344 100644
--- a/src/saveload/water_regions_sl.cpp
+++ b/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)
 	{}
diff --git a/src/sortlist_type.h b/src/sortlist_type.h
index fa2ce11377..7786463441 100644
--- a/src/sortlist_type.h
+++ b/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
 
diff --git a/src/sound/xaudio2_s.cpp b/src/sound/xaudio2_s.cpp
index e54c8c4abf..6c694d3c31 100644
--- a/src/sound/xaudio2_s.cpp
+++ b/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;
diff --git a/src/station_gui.cpp b/src/station_gui.cpp
index d0c49fcafb..cdc9464872 100644
--- a/src/station_gui.cpp
+++ b/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
diff --git a/src/town_gui.cpp b/src/town_gui.cpp
index 336434a441..5492bb76d2 100644
--- a/src/town_gui.cpp
+++ b/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.
diff --git a/src/viewport_gui.cpp b/src/viewport_gui.cpp
index 06930ae47a..6227f46c94 100644
--- a/src/viewport_gui.cpp
+++ b/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)