libobs, docs: Document intended use of obs_module_unload

obs_module_unload was never properly documented, so some plugins use it
to free resources, some use it to save data, etc. While libobs tries to
ensure all objects are shut down and destroyed before calling unload, if
another plugin is holding a strong reference, or if a reference leak has
occurred, libobs may need to call back into a plugin-provided object's
destroy function even after obs_module_unload has returned. If the
plugin has freed memory or other resources needed for the callback then
this likely results in a crash.

Going forward, we should document that obs_module_unload is now intended
only for saving data and releasing references, and that calling libobs
after it returns is not allowed. For cases where resource cleanup is
actually needed (for example, an external out of process helper needs to
be shut down or a release call to a hardware driver), a new
obs_module_destroy callback is intended to be added in a future version.

docs/sphinx/reference-modules.rst

@@ -55,7 +55,19 @@ to communicate with libobs and front-ends.
 
 .. function:: void obs_module_unload(void)
 
-   Optional: Called when the module is unloaded.
+   Optional: Called when libobs is shutting down and the module is about
+   to be unloaded. All libobs objects are still active and valid at this
+   point. Use this function to save user settings and release any strong
+   references that the module itself is holding to libobs objects (sources,
+   canvases, outputs, encoders, and services).
+
+   Do not attempt to release or destroy any still-active objects provided
+   by the module - ensure that they can continue functioning even after
+   returning from this function, as libobs may still need to call into the
+   module's callbacks (e.g., destroy) to clean up any remaining instances.
+
+   After this function returns, do not make any further libobs API calls
+   outside of libobs callbacks.
 
 ---------------------
 

libobs/obs-module.h

@@ -100,7 +100,21 @@ bool obs_module_load(void)
  */
 MODULE_EXPORT bool obs_module_load(void);
 
-/** Optional: Called when the module is unloaded.  */
+/**
+ * Optional: Called when libobs is shutting down and the module is about
+ * to be unloaded. All libobs objects are still active and valid at this
+ * point. Use this function to save user settings and release any strong
+ * references that the module itself is holding to libobs objects (sources,
+ * canvases, outputs, encoders, and services).
+ *
+ * Do not attempt to release or destroy any still-active objects provided
+ * by the module - ensure that they can continue functioning even after
+ * returning from this function, as libobs may still need to call into the
+ * module's callbacks (e.g., destroy) to clean up any remaining instances.
+ *
+ * After this function returns, do not make any further libobs API calls
+ * outside of libobs callbacks.
+ */
 MODULE_EXPORT void obs_module_unload(void);
 
 /** Optional: Called when all modules have finished loading */