[gimp] libgimp: add gimp_procedure_set_menu_label() and _set_documentation()

[Michael Natterer <mitch src gnome org>]

commit 0bec2bcdec7c1904646d6544e27aacf3b54dcdb9
Author: Michael Natterer <mitch gimp org>
Date:   Fri Aug 2 00:56:00 2019 +0200

    libgimp: add gimp_procedure_set_menu_label() and _set_documentation()
    
    which replace _set_strings(). Add more docs.

 libgimp/gimpprocedure.c         | 93 ++++++++++++++++++++++++++++-------------
 libgimp/gimpprocedure.h         |  9 ++--
 plug-ins/common/goat-exercise.c | 11 ++---
 plug-ins/help/help.c            | 12 ------
 4 files changed, 76 insertions(+), 49 deletions(-)
---
diff --git a/libgimp/gimpprocedure.c b/libgimp/gimpprocedure.c
index c9a85e9586..498a9db1fe 100644
--- a/libgimp/gimpprocedure.c
+++ b/libgimp/gimpprocedure.c
@@ -88,7 +88,6 @@ struct _GimpProcedurePrivate
 
 static void       gimp_procedure_finalize      (GObject         *object);
 
-static void       gimp_procedure_free_strings  (GimpProcedure   *procedure);
 static gboolean   gimp_procedure_validate_args (GimpProcedure   *procedure,
                                                 GParamSpec     **param_specs,
                                                 gint             n_param_specs,
@@ -126,10 +125,12 @@ gimp_procedure_finalize (GObject *object)
     procedure->priv->run_data_destroy (procedure->priv->run_data);
 
   g_clear_object  (&procedure->priv->plug_in);
-  g_clear_pointer (&procedure->priv->name, g_free);
-
-  gimp_procedure_free_strings (procedure);
 
+  g_clear_pointer (&procedure->priv->name,        g_free);
+  g_clear_pointer (&procedure->priv->menu_label,  g_free);
+  g_clear_pointer (&procedure->priv->blurb,       g_free);
+  g_clear_pointer (&procedure->priv->help,        g_free);
+  g_clear_pointer (&procedure->priv->help_id,     g_free);
   g_clear_pointer (&procedure->priv->authors,     g_free);
   g_clear_pointer (&procedure->priv->copyright,   g_free);
   g_clear_pointer (&procedure->priv->date,        g_free);
@@ -273,21 +274,29 @@ gimp_procedure_get_proc_type (GimpProcedure *procedure)
   return procedure->priv->proc_type;
 }
 
+/**
+ * gimp_procedure_set_menu_label:
+ * @procedure:  A #GimpProcedure.
+ * @menu_label: The @procedure's menu label.
+ *
+ * Sets the label to use for the @procedure's menu entry, The
+ * location(s) where to register in the menu hierarchy is chosen using
+ * gimp_procedure_add_menu_path().
+ *
+ * For translations of menu labels to work properly, this string
+ * should only be marked for translation but passed to this function
+ * untranslated, for example using N_("Label").
+ *
+ * Since: 3.0
+ **/
 void
-gimp_procedure_set_strings (GimpProcedure *procedure,
-                            const gchar   *menu_label,
-                            const gchar   *blurb,
-                            const gchar   *help,
-                            const gchar   *help_id)
+gimp_procedure_set_menu_label (GimpProcedure *procedure,
+                               const gchar   *menu_label)
 {
   g_return_if_fail (GIMP_IS_PROCEDURE (procedure));
 
-  gimp_procedure_free_strings (procedure);
-
-  procedure->priv->menu_label    = g_strdup (menu_label);
-  procedure->priv->blurb         = g_strdup (blurb);
-  procedure->priv->help          = g_strdup (help);
-  procedure->priv->help_id       = g_strdup (help_id);
+  g_clear_pointer (&procedure->priv->menu_label,  g_free);
+  procedure->priv->menu_label = g_strdup (menu_label);
 }
 
 /**
@@ -307,12 +316,49 @@ gimp_procedure_get_menu_label (GimpProcedure *procedure)
   return procedure->priv->menu_label;
 }
 
+/**
+ * gimp_procedure_set_documentation:
+ * @procedure: A #GimpProcedure.
+ * @blurb:     The @procedure's blurb.
+ * @help:      The @procedure's help text.
+ * @help_id:   The @procedure's help ID.
+ *
+ * @blurb is used as the @procedure's tooltip when represented in the UI,
+ * for example as a menu entry.
+ *
+ * For translations of tooltips to work properly, this string should
+ * only be marked for translation but passed to this function
+ * untranslated, for example using N_("Blurb").
+ *
+ * @help: is a free-form text that's meant as documentation for
+ * developers of scripts and plug-ins.
+ *
+ * Sets various documentation strings on @procedure.
+ *
+ * Since: 3.0
+ **/
+void
+gimp_procedure_set_documentation (GimpProcedure *procedure,
+                                  const gchar   *blurb,
+                                  const gchar   *help,
+                                  const gchar   *help_id)
+{
+  g_return_if_fail (GIMP_IS_PROCEDURE (procedure));
+
+  g_clear_pointer (&procedure->priv->blurb,       g_free);
+  g_clear_pointer (&procedure->priv->help,        g_free);
+  g_clear_pointer (&procedure->priv->help_id,     g_free);
+
+  procedure->priv->blurb   = g_strdup (blurb);
+  procedure->priv->help    = g_strdup (help);
+  procedure->priv->help_id = g_strdup (help_id);
+}
+
 /**
  * gimp_procedure_get_blurb:
  * @procedure: A #GimpProcedure.
  *
- * Returns: The procedure's blurb given in
- *          gimp_procedure_set_strings().
+ * Returns: The procedure's blurb given in gimp_procedure_set_help().
  *
  * Since: 3.0
  **/
@@ -329,7 +375,7 @@ gimp_procedure_get_blurb (GimpProcedure *procedure)
  * @procedure: A #GimpProcedure.
  *
  * Returns: The procedure's help text given in
- *          gimp_procedure_set_strings().
+ *          gimp_procedure_set_help().
  *
  * Since: 3.0
  **/
@@ -346,7 +392,7 @@ gimp_procedure_get_help (GimpProcedure *procedure)
  * @procedure: A #GimpProcedure.
  *
  * Returns: The procedure's help ID given in
- *          gimp_procedure_set_strings().
+ *          gimp_procedure_set_help().
  *
  * Since: 3.0
  **/
@@ -863,15 +909,6 @@ gimp_procedure_extension_ready (GimpProcedure *procedure)
 
 /*  private functions  */
 
-static void
-gimp_procedure_free_strings (GimpProcedure *procedure)
-{
-  g_clear_pointer (&procedure->priv->menu_label,  g_free);
-  g_clear_pointer (&procedure->priv->blurb,       g_free);
-  g_clear_pointer (&procedure->priv->help,        g_free);
-  g_clear_pointer (&procedure->priv->help_id,     g_free);
-}
-
 static gboolean
 gimp_procedure_validate_args (GimpProcedure  *procedure,
                               GParamSpec    **param_specs,
diff --git a/libgimp/gimpprocedure.h b/libgimp/gimpprocedure.h
index e26f2dd777..bd43c610ad 100644
--- a/libgimp/gimpprocedure.h
+++ b/libgimp/gimpprocedure.h
@@ -86,13 +86,14 @@ 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,
-                                                    const gchar       *menu_label,
+void             gimp_procedure_set_menu_label     (GimpProcedure     *procedure,
+                                                    const gchar       *menu_label);
+const gchar    * gimp_procedure_get_menu_label     (GimpProcedure     *procedure);
+
+void             gimp_procedure_set_documentation  (GimpProcedure     *procedure,
                                                     const gchar       *blurb,
                                                     const gchar       *help,
                                                     const gchar       *help_id);
-
-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);
 const gchar    * gimp_procedure_get_help_id        (GimpProcedure     *procedure);
diff --git a/plug-ins/common/goat-exercise.c b/plug-ins/common/goat-exercise.c
index a6077a2b06..712fc55696 100644
--- a/plug-ins/common/goat-exercise.c
+++ b/plug-ins/common/goat-exercise.c
@@ -103,11 +103,12 @@ goat_create_procedure (GimpPlugIn  *plug_in,
       procedure = gimp_procedure_new (plug_in, name, GIMP_PLUGIN,
                                       goat_run, NULL, NULL);
 
-      gimp_procedure_set_strings (procedure,
-                                  N_("Goat-exercise"),
-                                  N_("Exercise a goat"),
-                                  "takes a goat for a walk",
-                                  PLUG_IN_PROC);
+      gimp_procedure_set_menu_label (procedure, N_("Goat-exercise"));
+
+      gimp_procedure_set_documentation (procedure,
+                                        N_("Exercise a goat"),
+                                        "takes a goat for a walk",
+                                        PLUG_IN_PROC);
 
       gimp_procedure_set_attribution (procedure,
                                       "Øyvind Kolås <pippin gimp org>",
diff --git a/plug-ins/help/help.c b/plug-ins/help/help.c
index df6a31bee3..7d697d2f90 100644
--- a/plug-ins/help/help.c
+++ b/plug-ins/help/help.c
@@ -135,12 +135,6 @@ help_create_procedure (GimpPlugIn  *plug_in,
       procedure = gimp_procedure_new (plug_in, name, GIMP_EXTENSION,
                                       help_run, NULL, NULL);
 
-      gimp_procedure_set_strings (procedure,
-                                  NULL,
-                                  "", /* FIXME */
-                                  "", /* FIXME */
-                                  NULL);
-
       gimp_procedure_set_attribution (procedure,
                                       "Sven Neumann <sven gimp org>, "
                                       "Michael Natterer <mitch gimp org>, "
@@ -233,12 +227,6 @@ help_temp_proc_install (GimpPlugIn *plug_in)
   procedure = gimp_procedure_new (plug_in, GIMP_HELP_TEMP_EXT_PROC,
                                   GIMP_TEMPORARY, help_temp_run, NULL, NULL);
 
-  gimp_procedure_set_strings (procedure,
-                              NULL,
-                              "DON'T USE THIS ONE",
-                              "(Temporary procedure)",
-                              NULL);
-
   gimp_procedure_set_attribution (procedure,
                                   "Sven Neumann <sven gimp org>, "
                                   "Michael Natterer <mitch gimp org>"