Fix documentation

source/examples/HotReloadDemo/Shared/CppWidgetApi.h

@@ -1,47 +1,88 @@
-/* CppWidgetApi.h -- a C++ (not extern "C") surface living alongside
+/**
+ * @file CppWidgetApi.h
+ * @brief A C++ (not extern "C") surface living alongside
  * PluginApi.h's plain C one, in the SAME plugin build. Every member
  * function below keeps its real, compiler-mangled name; nothing here
  * needs special handling by source/HotReload, which classifies
  * symbols by their type and section, never by what their name looks
- * like -- see hot_reload.h's "REQUIREMENTS ON A HOT-RELOADABLE
- * MODULE" and README.md's "Hot reloading C++ symbols" for the full
- * picture.
+ * like -- see the "Requirements on a hot-reloadable module" section of
+ * hot_reload.h and the "Hot reloading C++ symbols" section of
+ * source/HotReload/README.md for the full picture.
  *
  * The two methods below are reached two different ways from
  * Host/Main.cpp, deliberately: see that file's comments for why.
  */
 #pragma once
 
+/**
+ * @brief A small C++ class whose members are defined in the plugin, not the host.
+ *
+ * Each member below keeps its real, compiler-mangled name and is reached a different way from
+ * Host/Main.cpp -- through the vtable, through a manually resolved mangled name, and (for the
+ * operator) not at all -- to show that all of them patch like any plain C function.
+ */
 class CppWidget
 {
 public:
+	/**
+	 * @brief Virtual, so that destroying a widget through a base pointer works across the
+	 *        boundary.
+	 */
 	virtual ~CppWidget() = default;
 
-	/* Virtual: Host/Main.cpp calls this through ordinary C++
+	/**
+	 * @brief Scales its input, through a virtual call.
+	 *
+	 * Virtual: Host/Main.cpp calls this through ordinary C++
 	 * polymorphic dispatch (widget->virtualTick(x)) and needs no
 	 * manual symbol lookup at all -- the call compiles down to an
 	 * indirect call through the object's vtable slot, not a direct
 	 * reference to this specific symbol, so it needs no link-time
-	 * dependency on whichever plugin build actually defines it. */
+	 * dependency on whichever plugin build actually defines it.
+	 *
+	 * @param input The value to scale.
+	 * @return V1: `input * 2`. V2: `input * 3`.
+	 */
 	virtual int virtualTick(int input);
 
-	/* An ordinary out-of-line method. Calling this as widget->tick(x)
+	/**
+	 * @brief Scales its input, through an ordinary out-of-line method.
+	 *
+	 * Calling this as widget->tick(x)
 	 * would compile to a direct call to CppWidget::tick's own mangled
 	 * symbol, which would need the Host to link against a plugin
 	 * build at build time -- exactly what hot-reloading a plugin
 	 * means avoiding. So Host/Main.cpp instead resolves it manually
 	 * by its mangled name via hot_reload_get_symbol(), the same way
-	 * it resolves PluginApi.h's plain C functions. */
+	 * it resolves PluginApi.h's plain C functions.
+	 *
+	 * @param input The value to scale.
+	 * @return V1: `input * 2`. V2: `input * 3`.
+	 */
 	int tick(int input);
 
-	/* An overloaded operator: mechanically just a function with an
+	/**
+	 * @brief An overloaded operator.
+	 *
+	 * Mechanically just a function with an
 	 * unusual mangled name, reached the same manual way as tick()
-	 * above. */
+	 * above.
+	 *
+	 * @param other Ignored; the operator only prints which build it is.
+	 * @return A new, empty widget.
+	 */
 	CppWidget operator+(const CppWidget& other) const;
 };
 
-/* The one entry point Host/Main.cpp looks up by a plain, human-typed
+/**
+ * @brief Creates a widget.
+ *
+ * The one entry point Host/Main.cpp looks up by a plain, human-typed
  * name -- extern "C" here for exactly the reason hot_reload.h
  * recommends it: something to hand a human-readable name to, without
- * needing to know or hardcode a mangled string. */
+ * needing to know or hardcode a mangled string.
+ *
+ * @return A new widget. The caller owns it and must `delete` it (safe across the plugin
+ *         boundary here because host and plugin share one C++ runtime and allocator).
+ */
 extern "C" CppWidget* make_cpp_widget();