Fix documentation

source/examples/HotReloadDemo/Shared/PluginApi.h

@@ -1,4 +1,6 @@
-/* PluginApi.h -- the contract PluginV1 and PluginV2 both implement,
+/**
+ * @file PluginApi.h
+ * @brief The contract PluginV1 and PluginV2 both implement,
  * and the Host loads by name. Every function here follows
  * cpp-style-guide.md section 11's rule for anything loaded at runtime:
  * plain C linkage, no classes or exceptions crossing the boundary.
@@ -15,31 +17,64 @@ extern "C"
 {
 #endif
 
-	/* Changes behavior between V1 and V2 -- watch this one get
-	 * HOT_RELOAD_SYMBOL_PATCHED. */
+	/**
+	 * @brief Scales its input, and prints which build it is.
+	 *
+	 * Changes behavior between V1 and V2 -- watch this one get
+	 * HOT_RELOAD_SYMBOL_PATCHED.
+	 *
+	 * @param input The value to scale.
+	 * @return V1: `input * 2`. V2: `input * 3`.
+	 */
 	int plugin_tick(int input);
 
-	/* Only in V1, gone in V2 -- watch this one get
-	 * HOT_RELOAD_SYMBOL_REMOVED, and the Host's stub take over for any
-	 * call still aimed at it afterwards. */
+	/**
+	 * @brief A feature that exists only in V1.
+	 *
+	 * Gone in V2 -- watch this one get HOT_RELOAD_SYMBOL_REMOVED, and the
+	 * Host's stub take over for any call still aimed at it afterwards.
+	 *
+	 * @param input The value to echo.
+	 * @return @p input, unchanged.
+	 */
 	int plugin_legacy_feature(int input);
 
-	/* Only in V2 -- watch this one get HOT_RELOAD_SYMBOL_ADDED, then
-	 * get called for the first time right after. */
+	/**
+	 * @brief A feature that exists only in V2.
+	 *
+	 * Watch this one get HOT_RELOAD_SYMBOL_ADDED, then get called for the
+	 * first time right after.
+	 *
+	 * @param input The value to scale.
+	 * @return `input * 10`.
+	 */
 	int plugin_new_feature(int input);
 
 #if defined(__GNUC__) || defined(__clang__)
-	/* Deliberately too small to safely hold a jump on any of this
-	 * library's backends (its patchable-function-entry padding is
-	 * overridden down to zero) -- watch this one get
-	 * HOT_RELOAD_SYMBOL_SKIPPED_TOO_SMALL rather than corrupt whatever
-	 * comes after it. MSVC has no equivalent per-function override
-	 * this demo could apply, so this one only exists on GCC/Clang.
+	/**
+	 * @brief An empty function, too small to hold the jump this library writes.
+	 *
+	 * Its patchable-function-entry padding is overridden down to zero, so
+	 * all that is left is the compiled empty body -- a handful of bytes,
+	 * fewer than the jump any of this library's backends writes on x86-64
+	 * and ARM64 at any optimization level. Watch this one get
+	 * HOT_RELOAD_SYMBOL_SKIPPED_TOO_SMALL rather than corrupt whatever comes
+	 * after it.
+	 *
+	 * Two configurations cannot promise "too small": unoptimized 32-bit x86
+	 * (its jump is only 5 bytes, which even an empty unoptimized function
+	 * reaches), and Windows, where a PE image carries no per-function size
+	 * and the library can only estimate one from the distance to the next
+	 * export. MSVC has no equivalent per-function override this demo could
+	 * apply, so this one only exists on GCC/Clang.
 	 */
-	__attribute__((patchable_function_entry(0))) int plugin_tiny_function(int input);
+	__attribute__((patchable_function_entry(0))) void plugin_tiny_function(void);
 #endif
 
-	/* An exported VARIABLE, not a function, sitting right next to
+	/**
+	 * @brief The build's version number: 1 in V1, 2 in V2.
+	 *
+	 * An exported VARIABLE, not a function, sitting right next to
 	 * real functions in the same library and changing value between
 	 * V1 and V2 just like plugin_tick's behavior does -- watch this
 	 * one get HOT_RELOAD_SYMBOL_SKIPPED_NOT_CODE. This is the