Fix documentation

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();