Fix documentation

source/tests/HotReloadTests/Main.cpp

@@ -1,4 +1,6 @@
-/* Exercises source/HotReload end to end against the real PluginV1/
+/**
+ * @file Main.cpp
+ * @brief Automated test suite: exercises source/HotReload end to end against the real PluginV1/
  * PluginV2 builds from source/examples/HotReloadDemo -- see
  * ../../examples/HotReloadDemo/Shared/PluginApi.h and CppWidgetApi.h
  * for what each exported name is there to prove. Deliberately does
@@ -22,8 +24,14 @@
 namespace
 {
 
+	/// Running count of failed CHECK() calls; main() returns non-zero when this is non-zero.
 	int g_failures = 0;
 
+	/// Records a failed check to stderr and increments g_failures. Called only through CHECK().
+	/// @param condition The check's result.
+	/// @param expression The checked expression, stringified.
+	/// @param file The source file the check appears in.
+	/// @param line The line the check appears on.
 	void checkImpl(bool condition, const char* expression, const char* file, int line)
 	{
 		if (!condition)
@@ -33,12 +41,18 @@ namespace
 		}
 	}
 
+/// Checks @p expr and records a failure (with its source location) if it is false, without
+/// relying on assert(), which NDEBUG (this project's default Release build) compiles out.
 #define CHECK(expr) checkImpl((expr), #expr, __FILE__, __LINE__)
 
+	/// The signature every plain-C export in PluginApi.h shares.
 	using PluginFunction = int (*)(int);
 
+	/// Every symbol event seen so far in the current reload, keyed by symbol name.
 	std::map<std::string, HotReloadSymbolEvent> g_events;
 
+	/// Records each event into g_events for later CHECK()s to inspect.
+	/// @param event Describes one symbol's outcome.
 	void onSymbolEvent(const HotReloadSymbolEventInfo* event, void* /*userData*/)
 	{
 		g_events[event->name] = event->kind;
@@ -46,6 +60,8 @@ namespace
 
 }
 
+/// Runs every check described in this file's @ref Main.cpp "file comment".
+/// @return 0 if every CHECK() passed, 1 otherwise.
 int main()
 {
 	HotReloadOptions options{};

source/tests/UndefinedSymbolFixture/src/Fixture.cpp

@@ -1,27 +1,37 @@
-/* A genuine ODR violation, kept deliberately: a non-inline static
+/**
+ * @file Fixture.cpp
+ * @brief A genuine ODR violation, kept deliberately: a non-inline static
  * class member that is declared but never given an out-of-class
  * definition. This compiles cleanly and links cleanly into a shared
  * library -- a shared library is allowed to keep undefined symbols by
  * default -- and only fails once something actually calls
  * trigger_undefined_symbol() below, ODR-using counter for the first
- * time. See source/HotReload/README.md's "hot_reload_last_error()"
- * section for the full story; HotReloadTests/Main.cpp loads this
- * fixture specifically to confirm hot_reload_last_error() reports
- * something useful for exactly this case, rather than leaving it a
- * silent "load failed" black box.
+ * time. See the "Diagnosing a failed load" section of
+ * source/HotReload/README.md for the full story; HotReloadTests/Main.cpp
+ * loads this fixture specifically to confirm hot_reload_last_error()
+ * reports something useful for exactly this case, rather than leaving it
+ * a silent "load failed" black box.
  */
+
+/// A class with one static member that is deliberately never defined -- see this file's comment.
 class HasUndefinedStaticMember
 {
 public:
+	/// ODR-uses counter, which is what actually triggers the undefined-symbol link error -- not
+	/// merely declaring or taking its address, and not merely loading this file's compiled output.
+	/// @return Never returns: linking the reference this creates is what fails.
 	static int useIt()
 	{
 		return counter;
 	}
 
 private:
-	static int counter; // declared, deliberately never defined anywhere
+	/// Declared, deliberately never defined anywhere -- see this file's comment.
+	static int counter;
 };
 
+/// The one exported entry point: calls into the class above to force the undefined-symbol error.
+/// @return Never returns a value in practice; see this file's comment.
 extern "C" int trigger_undefined_symbol()
 {
 	return HasUndefinedStaticMember::useIt();