From 53ca87d69351164f5041fa4c6f77c87fde006cc3 Mon Sep 17 00:00:00 2001
From: Michael Natterer <mitch@gimp.org>
Date: Thu, 1 Aug 2019 23:46:25 +0200
Subject: [PATCH] libgimp: cleanup and more docs for GimpProcedure

---
 libgimp/gimpprocedure.c | 39 ++++++++++++++++++++++++++++-----------
 libgimp/gimpprocedure.h | 15 ++++++++++++++-
 2 files changed, 42 insertions(+), 12 deletions(-)

diff --git a/libgimp/gimpprocedure.c b/libgimp/gimpprocedure.c
index 6cc83c6348..f217cc5995 100644
--- a/libgimp/gimpprocedure.c
+++ b/libgimp/gimpprocedure.c
@@ -130,6 +130,8 @@ gimp_procedure_finalize (GObject *object)
 
   gimp_procedure_free_strings (procedure);
 
+  g_clear_pointer (&procedure->priv->image_types, g_free);
+
   g_clear_pointer (&procedure->priv->icon_data, g_free);
   procedure->priv->icon_data_length = 0;
 
@@ -186,6 +188,11 @@ gimp_procedure_finalize (GObject *object)
  * created during a plug-ins lifetime. They must be added to the
  * #GimpPlugIn using gimp_plug_in_add_temp_procedure().
  *
+ * @run_func is called via gimp_procedure_run().
+ *
+ * For %GIMP_PLUGIN and %GIMP_EXTENSION procedures the call of
+ * @run_func is basically the lifetime of the plug-in.
+ *
  * Returns: a new #GimpProcedure.
  **/
 GimpProcedure  *
@@ -223,6 +230,14 @@ gimp_procedure_get_plug_in (GimpProcedure *procedure)
   return procedure->priv->plug_in;
 }
 
+const gchar *
+gimp_procedure_get_name (GimpProcedure *procedure)
+{
+  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);
+
+  return procedure->priv->name;
+}
+
 GimpPDBProcType
 gimp_procedure_get_proc_type (GimpProcedure *procedure)
 {
@@ -254,14 +269,6 @@ gimp_procedure_set_strings (GimpProcedure *procedure,
   procedure->priv->date          = g_strdup (date);
 }
 
-const gchar *
-gimp_procedure_get_name (GimpProcedure *procedure)
-{
-  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);
-
-  return procedure->priv->name;
-}
-
 const gchar *
 gimp_procedure_get_menu_label (GimpProcedure *procedure)
 {
@@ -605,9 +612,20 @@ gimp_procedure_new_return_values (GimpProcedure     *procedure,
   return args;
 }
 
+/**
+ * gimp_procedure_run:
+ * @procedure: a @GimpProcedure.
+ * @args:      the @procedure's arguments.
+ *
+ * Runs the procedure, calling the run_func given in gimp_procedure_new().
+ *
+ * Returns: (transfer-full): The @procedure's return values.
+ *
+ * Since: 3.0
+ **/
 GimpValueArray *
-gimp_procedure_run (GimpProcedure   *procedure,
-                    GimpValueArray  *args)
+gimp_procedure_run (GimpProcedure  *procedure,
+                    GimpValueArray *args)
 {
   GimpValueArray *return_vals;
   GError         *error = NULL;
@@ -688,7 +706,6 @@ gimp_procedure_free_strings (GimpProcedure *procedure)
   g_clear_pointer (&procedure->priv->author,      g_free);
   g_clear_pointer (&procedure->priv->copyright,   g_free);
   g_clear_pointer (&procedure->priv->date,        g_free);
-  g_clear_pointer (&procedure->priv->image_types, g_free);
 }
 
 static gboolean
diff --git a/libgimp/gimpprocedure.h b/libgimp/gimpprocedure.h
index 187480fbc1..1ca72cb78e 100644
--- a/libgimp/gimpprocedure.h
+++ b/libgimp/gimpprocedure.h
@@ -31,6 +31,19 @@ G_BEGIN_DECLS
 /* For information look into the C source or the html documentation */
 
 
+/**
+ * GimpRunFunc:
+ * @procedure: the #GimpProcedure that runs.
+ * @args:      the @procedure's arguments.
+ * @run_data:  the run_data given in gimp_procedure_new().
+ *
+ * The run function is run during the lifetime of the GIMP session,
+ * each time a plug-in procedure is called.
+ *
+ * Returns: (transfer full): the @procedure's return values.
+ *
+ * Since: 3.0
+ **/
 typedef GimpValueArray * (* GimpRunFunc) (GimpProcedure        *procedure,
                                           const GimpValueArray *args,
                                           gpointer              run_data);
@@ -70,6 +83,7 @@ GimpProcedure  * gimp_procedure_new                (GimpPlugIn        *plug_in,
                                                     GDestroyNotify     run_data_destroy);
 
 GimpPlugIn     * gimp_procedure_get_plug_in        (GimpProcedure     *procedure);
+const gchar    * gimp_procedure_get_name           (GimpProcedure     *procedure);
 GimpPDBProcType  gimp_procedure_get_proc_type      (GimpProcedure     *procedure);
 
 void             gimp_procedure_set_strings        (GimpProcedure     *procedure,
@@ -81,7 +95,6 @@ void             gimp_procedure_set_strings        (GimpProcedure     *procedure
                                                     const gchar       *copyright,
                                                     const gchar       *date);
 
-const gchar    * gimp_procedure_get_name           (GimpProcedure     *procedure);
 const gchar    * gimp_procedure_get_menu_label     (GimpProcedure     *procedure);
 const gchar    * gimp_procedure_get_blurb          (GimpProcedure     *procedure);
 const gchar    * gimp_procedure_get_help           (GimpProcedure     *procedure);