[gimp] libgimp: rename GimpLoad,SaveFunc to GimpRunLoad,SaveFunc

[Michael Natterer <mitch src gnome org>]

commit d067441c31767cd98c3ae22bf4c8238e9f495a65
Author: Michael Natterer <mitch gimp org>
Date:   Sun Aug 11 14:58:55 2019 +0200

    libgimp: rename GimpLoad,SaveFunc to GimpRunLoad,SaveFunc
    
    and document gimp_load,save_procedure_new().

 libgimp/gimploadprocedure.c | 45 +++++++++++++++++++++++++++++++++++++++------
 libgimp/gimploadprocedure.h | 14 +++++++-------
 libgimp/gimpsaveprocedure.c | 37 +++++++++++++++++++++++++++++++++++--
 libgimp/gimpsaveprocedure.h | 18 +++++++++---------
 4 files changed, 90 insertions(+), 24 deletions(-)
---
diff --git a/libgimp/gimploadprocedure.c b/libgimp/gimploadprocedure.c
index 76e2e5b9b8..a0f4a0d155 100644
--- a/libgimp/gimploadprocedure.c
+++ b/libgimp/gimploadprocedure.c
@@ -29,12 +29,12 @@
 
 struct _GimpLoadProcedurePrivate
 {
-  GimpLoadFunc    run_func;
-  gpointer        run_data;
-  GDestroyNotify  run_data_destroy;
+  GimpRunLoadFunc  run_func;
+  gpointer         run_data;
+  GDestroyNotify   run_data_destroy;
 
-  gboolean        handles_raw;
-  gchar          *thumbnail_proc;
+  gboolean         handles_raw;
+  gchar           *thumbnail_proc;
 };
 
 
@@ -204,11 +204,44 @@ gimp_load_procedure_run (GimpProcedure        *procedure,
 
 /*  public functions  */
 
+/**
+ * gimp_load_procedure_new:
+ * @plug_in:          a #GimpPlugIn.
+ * @name:             the new procedure's name.
+ * @proc_type:        the new procedure's #GimpPDBProcType.
+ * @run_func:         the run function for the new procedure.
+ * @run_data:         user data passed to @run_func.
+ * @run_data_destroy: (nullable): free function for @run_data, or %NULL.
+ *
+ * Creates a new load procedure named @name which will call @run_func
+ * when invoked.
+ *
+ * See gimp_procedure_new() for information about @proc_type.
+ *
+ * #GimpLoadProcedure is a #GimpProcedure subclass that makes it easier
+ * to write file load procedures.
+ *
+ * It automatically adds the standard
+ *
+ * (run-mode, uri, raw-uri)
+ *
+ * arguments of a load procedure. It is possible to add additional
+ * arguments.
+ *
+ * When invoked via gimp_procedure_run(), it unpacks these standard
+ * arguemnts and calls @run_func which is a #GimpRunLoadFunc. The
+ * "args" #GimpValueArray of #GimpRunLoadFunc only contains
+ * additionally added arguments.
+ *
+ * Returns: a new #GimpProcedure.
+ *
+ * Since: 3.0
+ **/
 GimpProcedure  *
 gimp_load_procedure_new (GimpPlugIn      *plug_in,
                          const gchar     *name,
                          GimpPDBProcType  proc_type,
-                         GimpLoadFunc     run_func,
+                         GimpRunLoadFunc  run_func,
                          gpointer         run_data,
                          GDestroyNotify   run_data_destroy)
 {
diff --git a/libgimp/gimploadprocedure.h b/libgimp/gimploadprocedure.h
index 4011fbe6a3..9528297d99 100644
--- a/libgimp/gimploadprocedure.h
+++ b/libgimp/gimploadprocedure.h
@@ -30,7 +30,7 @@ G_BEGIN_DECLS
 
 
 /**
- * GimpLoadFunc:
+ * GimpRunLoadFunc:
  * @procedure:   the #GimpProcedure that runs.
  * @run_mode:    the #GimpRunMode.
  * @file:        the #GFile to load from.
@@ -44,11 +44,11 @@ G_BEGIN_DECLS
  *
  * Since: 3.0
  **/
-typedef GimpValueArray * (* GimpLoadFunc) (GimpProcedure        *procedure,
-                                           GimpRunMode           run_mode,
-                                           GFile                *file,
-                                           const GimpValueArray *args,
-                                           gpointer              run_data);
+typedef GimpValueArray * (* GimpRunLoadFunc) (GimpProcedure        *procedure,
+                                              GimpRunMode           run_mode,
+                                              GFile                *file,
+                                              const GimpValueArray *args,
+                                              gpointer              run_data);
 
 
 #define GIMP_TYPE_LOAD_PROCEDURE            (gimp_load_procedure_get_type ())
@@ -81,7 +81,7 @@ GType           gimp_load_procedure_get_type             (void) G_GNUC_CONST;
 GimpProcedure * gimp_load_procedure_new                  (GimpPlugIn        *plug_in,
                                                           const gchar       *name,
                                                           GimpPDBProcType    proc_type,
-                                                          GimpLoadFunc       run_func,
+                                                          GimpRunLoadFunc    run_func,
                                                           gpointer           run_data,
                                                           GDestroyNotify     run_data_destroy);
 
diff --git a/libgimp/gimpsaveprocedure.c b/libgimp/gimpsaveprocedure.c
index 01e6e61f02..b8b41633fb 100644
--- a/libgimp/gimpsaveprocedure.c
+++ b/libgimp/gimpsaveprocedure.c
@@ -29,7 +29,7 @@
 
 struct _GimpSaveProcedurePrivate
 {
-  GimpSaveFunc    run_func;
+  GimpRunSaveFunc run_func;
   gpointer        run_data;
   GDestroyNotify  run_data_destroy;
 };
@@ -192,11 +192,44 @@ gimp_save_procedure_run (GimpProcedure        *procedure,
 
 /*  public functions  */
 
+/**
+ * gimp_save_procedure_new:
+ * @plug_in:          a #GimpPlugIn.
+ * @name:             the new procedure's name.
+ * @proc_type:        the new procedure's #GimpPDBProcType.
+ * @run_func:         the run function for the new procedure.
+ * @run_data:         user data passed to @run_func.
+ * @run_data_destroy: (nullable): free function for @run_data, or %NULL.
+ *
+ * Creates a new save procedure named @name which will call @run_func
+ * when invoked.
+ *
+ * See gimp_procedure_new() for information about @proc_type.
+ *
+ * #GimpSaveProcedure is a #GimpProcedure subclass that makes it easier
+ * to write file save procedures.
+ *
+ * It automatically adds the standard
+ *
+ * (run-mode, image-id, drawable-id, uri, raw-uri)
+ *
+ * arguments of a save procedure. It is possible to add additional
+ * arguments.
+ *
+ * When invoked via gimp_procedure_run(), it unpacks these standard
+ * arguemnts and calls @run_func which is a #GimpRunSaveFunc. The
+ * "args" #GimpValueArray of #GimpRunSaveFunc only contains
+ * additionally added arguments.
+ *
+ * Returns: a new #GimpProcedure.
+ *
+ * Since: 3.0
+ **/
 GimpProcedure  *
 gimp_save_procedure_new (GimpPlugIn      *plug_in,
                          const gchar     *name,
                          GimpPDBProcType  proc_type,
-                         GimpSaveFunc     run_func,
+                         GimpRunSaveFunc  run_func,
                          gpointer         run_data,
                          GDestroyNotify   run_data_destroy)
 {
diff --git a/libgimp/gimpsaveprocedure.h b/libgimp/gimpsaveprocedure.h
index 2755487cc1..0e5000452d 100644
--- a/libgimp/gimpsaveprocedure.h
+++ b/libgimp/gimpsaveprocedure.h
@@ -30,7 +30,7 @@ G_BEGIN_DECLS
 
 
 /**
- * GimpSaveFunc:
+ * GimpRunSaveFunc:
  * @procedure:   the #GimpProcedure that runs.
  * @run_mode:    the #GimpRunMode.
  * @image_id:    the image to save.
@@ -46,13 +46,13 @@ G_BEGIN_DECLS
  *
  * Since: 3.0
  **/
-typedef GimpValueArray * (* GimpSaveFunc) (GimpProcedure        *procedure,
-                                           GimpRunMode           run_mode,
-                                           gint32                image_id,
-                                           gint32                drawable_id,
-                                           GFile                *file,
-                                           const GimpValueArray *args,
-                                           gpointer              run_data);
+typedef GimpValueArray * (* GimpRunSaveFunc) (GimpProcedure        *procedure,
+                                              GimpRunMode           run_mode,
+                                              gint32                image_id,
+                                              gint32                drawable_id,
+                                              GFile                *file,
+                                              const GimpValueArray *args,
+                                              gpointer              run_data);
 
 
 #define GIMP_TYPE_SAVE_PROCEDURE            (gimp_save_procedure_get_type ())
@@ -85,7 +85,7 @@ GType           gimp_save_procedure_get_type (void) G_GNUC_CONST;
 GimpProcedure * gimp_save_procedure_new      (GimpPlugIn      *plug_in,
                                               const gchar     *name,
                                               GimpPDBProcType  proc_type,
-                                              GimpSaveFunc     run_func,
+                                              GimpRunSaveFunc  run_func,
                                               gpointer         run_data,
                                               GDestroyNotify   run_data_destroy);