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

src/os/macosx/osx_stdafx.h

@@ -74,7 +74,7 @@ typedef float CGFloat;
 #endif /* __LP64__ */
 #endif /* CGFLOAT_DEFINED */
 
-/* OS X has a non-const iconv. */
+/** OS X has a non-const iconv. */
 #define HAVE_NON_CONST_ICONV
 
 #endif /* MACOS_STDAFX_H */

src/os/windows/win32.cpp

@@ -17,7 +17,7 @@
 #include <fcntl.h>
 #include <mmsystem.h>
 #include <regstr.h>
-#define NO_SHOBJIDL_SORTDIRECTION // Avoid multiple definition of SORT_ASCENDING
+#define NO_SHOBJIDL_SORTDIRECTION /**< Avoid multiple definition of SORT_ASCENDING. */
 #include <shlobj.h> /* SHGetFolderPath */
 #include <shellapi.h>
 #include <winnls.h>
@@ -459,10 +459,10 @@ int OTTDStringCompare(std::string_view s1, std::string_view s2)
 	static const PFNCOMPARESTRINGEX _CompareStringEx = GetKernel32Function("CompareStringEx");
 
 #ifndef SORT_DIGITSASNUMBERS
-#	define SORT_DIGITSASNUMBERS 0x00000008  // use digits as numbers sort method
+#	define SORT_DIGITSASNUMBERS 0x00000008  /**< Use digits as numbers sort method. */
 #endif
 #ifndef LINGUISTIC_IGNORECASE
-#	define LINGUISTIC_IGNORECASE 0x00000010 // linguistically appropriate 'ignore case'
+#	define LINGUISTIC_IGNORECASE 0x00000010 /**< Linguistically appropriate 'ignore case'. */
 #endif
 
 	int len_s1 = MultiByteToWideChar(CP_UTF8, 0, s1.data(), (int)s1.size(), nullptr, 0);

src/saveload/oldloader.h

@@ -109,22 +109,19 @@ inline uint32_t ReadUint32(LoadgameState &ls)
 	return x | ReadUint16(ls) << 16;
 }
 
-/* Help:
- *  - OCL_SVAR: load 'type' to offset 'offset' in a struct of type 'base', which must also
- *       be given via base in LoadChunk() as real pointer
- *  - OCL_VAR: load 'type' to a global var
- *  - OCL_END: every struct must end with this
- *  - OCL_NULL: read 'amount' of bytes and send them to /dev/null or something
- *  - OCL_CHUNK: load another proc to load a part of the savegame, 'amount' times
- *  - OCL_ASSERT: to check if we are really at the place we expect to be.. because old savegames are too binary to be sure ;)
- */
+/** Load 'type' to offset 'offset' in a struct of type 'base', which must also be given via base in LoadChunk() as real pointer. */
 #define OCL_SVAR(type, base, offset)         { type,                 1, nullptr, [] (void *b) -> void * { return std::addressof(static_cast<base *>(b)->offset); }, nullptr }
+/** Load 'type' to a global var. */
 #define OCL_VAR(type, amount, pointer)       { type,            amount, pointer, nullptr, nullptr }
+/** Every struct must end with this. */
 #define OCL_END()                            { OC_END,               0, nullptr, nullptr, nullptr }
 #define OCL_CNULL(type, amount)              { OC_NULL | type,  amount, nullptr, nullptr, nullptr }
 #define OCL_CCHUNK(type, amount, proc)       { OC_CHUNK | type, amount, nullptr, nullptr, proc }
+/** To check if we are really at the place we expect to be.. because old savegames are too binary to be sure ;) */
 #define OCL_ASSERT(type, size)               { OC_ASSERT | type,     1, (void *)(size_t)size, nullptr, nullptr }
+/** Read 'amount' of bytes and send them to /dev/null or something. */
 #define OCL_NULL(amount)        OCL_CNULL((OldChunkType)0, amount)
+/** Load another proc to load a part of the savegame, 'amount' times. */
 #define OCL_CHUNK(amount, proc) OCL_CCHUNK((OldChunkType)0, amount, proc)
 
 #endif /* OLDLOADER_H */

src/stdafx.h

@@ -186,7 +186,7 @@ using namespace std::literals::string_view_literals;
 #endif
 #define PACK(type_dec) PACK_N(type_dec, 1)
 
-/*
+/** @def debug_inline
  * When making a (pure) debug build, the compiler will by default disable
  * inlining of functions. This has a detrimental effect on the performance of
  * debug builds, especially when more and more trivial (wrapper) functions get

src/table/autorail.h

@@ -15,7 +15,7 @@
  *   0      1      2      3     4     5
  */
 
-/* mark invalid tiles red */
+/** Mark invalid tiles red. */
 #define RED(c) -c
 
 /**

src/table/engines.h

@@ -87,14 +87,13 @@
  */
 #define MA(a, b, c, d, e) { CalendarTime::DAYS_TILL_ORIGINAL_BASE_YEAR + a, TimerGameCalendar::Year{c}, TimerGameCalendar::Year{d}, b, 20, e, INVALID_CARGO, CT_INVALID, 0, 8, EngineMiscFlags{}, VehicleCallbackMasks{}, 0, {}, STR_EMPTY, Ticks::CARGO_AGING_TICKS, EngineID::Invalid() }
 
-/* Climates
- * T = Temperate
- * A = Sub-Arctic
- * S = Sub-Tropic
- * Y = Toyland */
+/** Climate temperate. */
 #define T LandscapeType::Temperate
+/** Climate sub-arctic. */
 #define A LandscapeType::Arctic
+/** Climate sub-tropic. */
 #define S LandscapeType::Tropic
+/** Climate toyland. */
 #define Y LandscapeType::Toyland
 static constexpr EngineInfo _orig_engine_info[] = {
 	/*      base_intro     base_life
@@ -394,7 +393,7 @@ static constexpr EngineInfo _orig_engine_info[] = {
 #define E EC_ELECTRIC
 #define N EC_MONORAIL
 #define V EC_MAGLEV
-/* Wagons always have engine type 0, i.e. steam. */
+/** Wagons always have engine type 0, i.e. steam. */
 #define A EC_STEAM
 
 #define R RAILTYPE_RAIL

src/table/newgrf_debug_data.h

@@ -12,13 +12,13 @@
 #include "../newgrf_roadtype.h"
 #include "../newgrf_roadstop.h"
 
-/* Helper for filling property tables */
+/** Helper for filling property tables. */
 #define NIP(prop, base_class, variable, type, name) { name, [] (const void *b) -> uint32_t { return static_cast<const base_class *>(b)->variable; }, prop, type }
 
-/* Helper for filling callback tables */
+/** Helper for filling callback tables. */
 #define NIC(cb_id, base_class, variable, bit) { #cb_id, [] (const void *b) -> uint32_t { return static_cast<const base_class *>(b)->variable.base(); }, bit, cb_id }
 
-/* Helper for filling variable tables */
+/** Helper for filling variable tables. */
 #define NIV(var, name) { name, var }
 
 

src/table/object_land.h

@@ -108,14 +108,13 @@ static const DrawTileSpriteSpan _object_hq[] = {
 
 #define M(name, size, build_cost_multiplier, clear_cost_multiplier, height, introduction_date, climate, gen_amount, flags) {{ObjectClassID::Invalid(), 0}, StandardGRFFileProps{}, AnimationInfo<ObjectAnimationTriggers>{}, name, climate, size, build_cost_multiplier, clear_cost_multiplier, introduction_date, CalendarTime::MAX_DATE + 1, flags, ObjectCallbackMasks{}, height, 1, gen_amount, {}}
 
-/* Climates
- * T = Temperate
- * A = Sub-Arctic
- * S = Sub-Tropic
- * Y = Toyland */
+/** Climate temperate. */
 #define T LandscapeType::Temperate
+/** Climate sub-arctic. */
 #define A LandscapeType::Arctic
+/** Climate sub-tropic. */
 #define S LandscapeType::Tropic
+/** Climate toyland. */
 #define Y LandscapeType::Toyland
 /** Specification of the original object structures. */
 extern const ObjectSpec _original_objects[] = {

src/tgp.cpp

@@ -591,7 +591,7 @@ static void HeightMapCurves(uint level)
 		Height x; ///< The height to scale from.
 		Height y; ///< The height to scale to.
 	};
-	/* Scaled curve maps; value is in height_ts. */
+	/** Scaled curve maps; value is in height_ts. */
 #define F(fraction) ((Height)(fraction * mh))
 	const ControlPoint curve_map_1[] = { { F(0.0), F(0.0) },                       { F(0.8), F(0.13) },                       { F(1.0), F(0.4)  } };
 	const ControlPoint curve_map_2[] = { { F(0.0), F(0.0) }, { F(0.53), F(0.13) }, { F(0.8), F(0.27) },                       { F(1.0), F(0.6)  } };