# HG changeset patch
# Node ID e4190ddf3fdc
# Parent  273e94647707
diff --git a/gplugin/reference/genie.md b/gplugin/reference/genie.md
--- a/gplugin/reference/genie.md
+++ b/gplugin/reference/genie.md
@@ -21,6 +21,9 @@
 ```genie
 uses GPlugin
 
+/* You need to create a class for your plugin info. This is pretty simple as you
+ * can see in the example below.
+ */
 namespace BasicPlugin
 	class Info : GPlugin.PluginInfo
 		construct()
@@ -39,17 +42,36 @@
 				description: "description"
 			)
 
+/* gplugin_query is called when searching for plugins. The function should
+ * return an instance of the PluginInfo class you created above. If something
+ * went wrong, you can set error with an error message.
+ */
 def gplugin_query(out error : Error) : GPlugin.PluginInfo
 	error = null
 
 	return new BasicPlugin.Info()
 
+/* gplugin_load is called when your plugin is loaded in the application. If
+ * something isn't quite right, you can return false and optionally set error,
+ * to signify that something went wrong and stop your plugin from being loaded.
+ */
 def gplugin_load(plugin : GPlugin.Plugin, out error : Error) : bool
 	error = null
 
 	return true
 
-def gplugin_unload(plugin : GPlugin.Plugin, out error : Error) : bool
+/* gplugin_plugin_unload is called when your plugin is unloaded in the
+ * application. The shutdown parameter tells your plugin whether or not the
+ * application is shutting down. For example, if a user unloads your plugin,
+ * shutdown will be false, but if the program is shutting down, shutdown will be
+ * true.
+ *
+ * If something went wrong with the unload or the plugin isn't ready to be
+ * unloaded, you can return false, and optionally set error, here to stop it
+ * from being unloaded. Note if shutdown is true, the return value is not
+ * honored.
+ */
+def gplugin_unload(plugin : GPlugin.Plugin, shutdown: bool, out error : Error) : bool
 	error = null
 
 	return true
diff --git a/gplugin/reference/lua.md b/gplugin/reference/lua.md
--- a/gplugin/reference/lua.md
+++ b/gplugin/reference/lua.md
@@ -17,6 +17,8 @@
 local lgi = require "lgi"
 local GPlugin = lgi.GPlugin
 
+-- gplugin_plugin_query is called when searching for plugins. The only thing
+-- this function should do, is return a GPlugin.PluginInfo instance.
 function gplugin_query()
     return GPlugin.PluginInfo {
         id = "gplugin-lua/basic-plugin",
@@ -32,11 +34,23 @@
     }
 end
 
+-- gplugin_load is called when your plugin is loaded in the application. If
+-- something isn't quite right, you can return false or call error() to signify
+-- that something went wrong and stop your plugin from being loaded.
 function gplugin_load(plugin)
     return true
 end
 
-function gplugin_unload(plugin)
+-- gplugin_plugin_unload is called when your plugin is unloaded in the
+-- application. The shutdown parameter tells your plugin whether or not the
+-- application is shutting down. For example, if a user unloads your plugin,
+-- shutdown will be false, but if the program is shutting down, shutdown will be
+-- true.
+--
+-- If something went wrong with the unload or the plugin isn't ready to be
+-- unloaded, you can return false here to stop it from being unloaded. Note if
+-- shutdown is true, the return value is not honored.
+function gplugin_unload(plugin, shutdown)
     return true
 end
 ```
diff --git a/gplugin/reference/native-plugins.md b/gplugin/reference/native-plugins.md
--- a/gplugin/reference/native-plugins.md
+++ b/gplugin/reference/native-plugins.md
@@ -63,9 +63,15 @@
  * g_set_error() and return %FALSE. This function needs to match the signature
  * of GPluginNativePluginUnloadFunc, and it will be passed to
  * GPLUGIN_NATIVE_PLUGIN_DECLARE which will export it properly.
+ *
+ * The shutdown parameter is set to TRUE when the application is shutting down.
+ * This is useful if you're using a library where you can only initialize it
+ * once. In this case, you'd typically always return FALSE here, but with the
+ * shutdown parameter, you can return FALSE when shutdown is FALSE, but then
+ * properly uninitialize the library when shutdown is TRUE.
  */
 static gboolean
-gplugin_native_basic_plugin_unload(GPluginPlugin *plugin, GError *error) {
+gplugin_native_basic_plugin_unload(GPluginPlugin *plugin, gboolean shutdown, GError *error) {
 	return TRUE;
 }
 
diff --git a/gplugin/reference/perl5.md b/gplugin/reference/perl5.md
--- a/gplugin/reference/perl5.md
+++ b/gplugin/reference/perl5.md
@@ -20,6 +20,8 @@
 
 Glib::Object::Introspection->setup(basename => "GPlugin", version => "1.0", package=> "GPlugin");
 
+# gplugin_plugin_query is called when searching for plugins. The only thing this
+# function should do, is return a GPlugin.PluginInfo instance.
 sub gplugin_query {
 	return GPlugin::PluginInfo->new(
 		id => "gplugin/perl5-basic-plugin",
@@ -35,11 +37,27 @@
 	);
 }
 
+# gplugin_plugin_load is called when your plugin is loaded in the application.
+# If something isn't quite right, you can return non zero or call die() to
+# signify that something went wrong and stop your plugin from being loaded.
 sub gplugin_load {
+	my $plugin = shift;
+
 	return 0;
 }
 
+# gplugin_plugin_unload is called when your plugin is unloaded in the
+# application. The shutdown parameter tells your plugin whether or not the
+# application is shutting down. For example, if a user unloads your plugin,
+# shutdown will be 1, but if the program is shutting down, shutdown will be 0.
+#
+# If something went wrong with the unload or the plugin isn't ready to be
+# unloaded you can return 1 here to stop it from being unloaded. Note if
+# shutdown is 0, the return value is not honored.
 sub gplugin_unload {
+	my $plugin = shift;
+	my $shutdown = shift;
+
 	return 0;
 }
 ```
diff --git a/gplugin/reference/python3.md b/gplugin/reference/python3.md
--- a/gplugin/reference/python3.md
+++ b/gplugin/reference/python3.md
@@ -20,6 +20,8 @@
 gi.require_version("GPlugin", "0.0")
 from gi.repository import GPlugin
 
+# gplugin_plugin_query is called when searching for plugins. The only thing this
+# function should do, is return a GPlugin.PluginInfo instance.
 def gplugin_plugin_query():
     return GPlugin.PluginInfo(
         id="gplugin-python/basic-plugin",
@@ -34,10 +36,22 @@
         description="description",
     )
 
+# gplugin_plugin_load is called when your plugin is loaded in the application.
+# If something isn't quite right, you can return False or throw an exception to
+# signify that something went wrong and stop your plugin from being loaded.
 def gplugin_plugin_load(plugin):
     return True
 
-def gplugin_plugin_unload(plugin):
+# gplugin_plugin_unload is called when your plugin is unloaded in the
+# application. The shutdown parameter tells your plugin whether or not the
+# application is shutting down. For example, if a user unloads your plugin,
+# shutdown will be False, but if the program is shutting down, shutdown will be
+# True.
+#
+# If something went wrong with the unload or the plugin isn't ready to be
+# unloaded, you can return False here to stop it from being unloaded. Note if
+# shutdown is True, the return value is not honored.
+def gplugin_plugin_unload(plugin, shutdown):
     return True
 ```
 
diff --git a/gplugin/reference/vala.md b/gplugin/reference/vala.md
--- a/gplugin/reference/vala.md
+++ b/gplugin/reference/vala.md
@@ -23,6 +23,9 @@
 
 namespace BasicPlugin {
 
+/* You need to create a class for your plugin info. This is pretty simple as you
+ * can see in the example below.
+ */
 public class Info : GPlugin.PluginInfo {
 	public Info() {
 		string[] authors = {"author1"};
@@ -44,18 +47,37 @@
 
 }
 
+/* gplugin_query is called when searching for plugins. The function should
+ * return an instance of the PluginInfo class you created above. If something
+ * went wrong, you can set error with an error message.
+ */
 public GPlugin.PluginInfo gplugin_query(out Error error) {
 	error = null;
 
 	return new BasicPlugin.Info();
 }
 
+/* gplugin_load is called when your plugin is loaded in the application. If
+ * something isn't quite right, you can return false and optionally set error,
+ * to signify that something went wrong and stop your plugin from being loaded.
+ */
 public bool gplugin_load(GPlugin.Plugin plugin, out Error error) {
 	error = null;
 
 	return true;
 }
 
+/* gplugin_plugin_unload is called when your plugin is unloaded in the
+ * application. The shutdown parameter tells your plugin whether or not the
+ * application is shutting down. For example, if a user unloads your plugin,
+ * shutdown will be false, but if the program is shutting down, shutdown will be
+ * true.
+ *
+ * If something went wrong with the unload or the plugin isn't ready to be
+ * unloaded, you can return false, and optionally set error, here to stop it
+ * from being unloaded. Note if shutdown is true, the return value is not
+ * honored.
+ */
 public bool gplugin_unload(GPlugin.Plugin plugin, out Error error) {
 	error = null;
 
