Fix documentation

source/examples/HotReloadDemo/Host/Main.cpp

@@ -1,4 +1,6 @@
-/* Main.cpp -- loads PluginV1, calls into it, reloads to PluginV2, and
+/**
+ * @file Main.cpp
+ * @brief Scripted, deterministic demo: loads PluginV1, calls into it, reloads to PluginV2, and
  * calls the SAME already-resolved function pointers again to show
  * they now run the new code -- without the Host re-resolving anything.
  * Along the way this exercises every HotReloadSymbolEvent kind: watch
@@ -17,33 +19,40 @@
 namespace
 {
 
+	/// The signature every plain-C export in PluginApi.h shares.
 	using PluginFunction = int (*)(int);
 
-	// CppWidget::tick's real ABI: an implicit this-pointer followed by
-	// its one declared parameter, same calling convention the
-	// compiler itself would generate for widget->tick(x) -- this is
-	// just spelling that out explicitly so it can be called through a
-	// manually-resolved address instead.
+	/// CppWidget::tick's real ABI: an implicit this-pointer followed by
+	/// its one declared parameter, same calling convention the
+	/// compiler itself would generate for widget->tick(x) -- this is
+	/// just spelling that out explicitly so it can be called through a
+	/// manually-resolved address instead.
 	using CppWidgetTickFunction = int (*)(CppWidget*, int);
 
+	/// Stands in for @c plugin_legacy_feature once V2 removes it.
+	/// @return Always -1.
 	int hostSideDeletedFunctionStub(int)
 	{
 		std::printf("    !! called a deleted plugin function -- this is the Host's stub, not a crash !!\n");
 		return -1;
 	}
 
-	/* Runs once per HOT_RELOAD_SYMBOL_REMOVED, before onSymbolEvent
-	 * below sees the same event -- see hot_reload.h's doc comment on
-	 * HotReloadDeletedSymbolFn. Redirecting a removed function to a
-	 * stub living in the HOST executable (not in either plugin build)
-	 * demonstrates that the target of a patch can be anywhere at all,
-	 * not just inside the module being reloaded. */
+	/// Runs once per HOT_RELOAD_SYMBOL_REMOVED, before onSymbolEvent
+	/// below sees the same event -- see hot_reload.h's doc comment on
+	/// HotReloadDeletedSymbolFn. Redirecting a removed function to a
+	/// stub living in the HOST executable (not in either plugin build)
+	/// demonstrates that the target of a patch can be anywhere at all,
+	/// not just inside the module being reloaded.
+	/// @param symbolName The removed function's real (possibly mangled) name.
+	/// @return The host stub to redirect old callers to.
 	void* onDeletedSymbol(const char* symbolName, void* /*userData*/)
 	{
 		std::printf("  [event] REMOVED    %-22s -> redirecting old callers to the Host's stub\n", symbolName);
 		return reinterpret_cast<void*>(&hostSideDeletedFunctionStub);
 	}
 
+	/// @param kind The event kind to name.
+	/// @return A short, human-readable label for @p kind.
 	const char* eventKindName(HotReloadSymbolEvent kind)
 	{
 		switch (kind)
@@ -64,6 +73,8 @@ namespace
 		return "?";
 	}
 
+	/// Logs every symbol event except REMOVED, which onDeletedSymbol() already logs.
+	/// @param event Describes one symbol's outcome.
 	void onSymbolEvent(const HotReloadSymbolEventInfo* event, void* /*userData*/)
 	{
 		// REMOVED is already reported, with more context, by
@@ -85,6 +96,10 @@ namespace
 
 }
 
+/// Runs the scripted demo described in this file's @ref Main.cpp "file comment".
+/// @param argc Argument count.
+/// @param argv `argv[1]`/`argv[2]`, if present, override the compiled-in plugin paths.
+/// @return 0 on success, 1 if the context or either load/reload step failed.
 int main(int argc, char** argv)
 {
 	std::string pluginV1Path = argc > 1 ? argv[1] : PLUGIN_V1_PATH;