[gimp] libgimp: update annotations for gimp_install_procedure() and...

[Jehan <jehanp src gnome org>]

commit c20645054cc9a044d7c0f677180e9fb8cb14c896
Author: Jehan <jehan girinstud io>
Date:   Thu Jul 25 19:27:16 2019 +0200

    libgimp: update annotations for gimp_install_procedure() and...
    
    ... GimpRunProc function type.
    In gimp_install_procedure(), make sure that @params and @return_vals are
    processed as arrays, otherwise they are unusable.
    
    As for the run procedure, make so that @return_vals and @n_return_vals
    are considered as returned values. In Python binding for instance, that
    makes these not parameters anymore, but actually returnable by the run
    function.
    
    With these changes, I made the first fully functional GI Python plug-in,
    which just creates a new image and a display for this image. Still a lot
    to improve clearly, but we are on the right track. :-)

 libgimp/gimp.c | 30 +++++++++++++++---------------
 libgimp/gimp.h |  4 ++--
 2 files changed, 17 insertions(+), 17 deletions(-)
---
diff --git a/libgimp/gimp.c b/libgimp/gimp.c
index 2e84037d80..a9cc9e6136 100644
--- a/libgimp/gimp.c
+++ b/libgimp/gimp.c
@@ -741,21 +741,21 @@ gimp_quit (void)
 
 /**
  * gimp_install_procedure:
- * @name:          the procedure's name.
- * @blurb:         a short text describing what the procedure does.
- * @help:          the help text for the procedure (usually considerably
- *                 longer than @blurb).
- * @author:        the procedure's author(s).
- * @copyright:     the procedure's copyright.
- * @date:          the date the procedure was added.
- * @menu_label:    the label to use for the procedure's menu entry,
- *                 or #NULL if the procedure has no menu entry.
- * @image_types:   the drawable types the procedure can handle.
- * @type:          the type of the procedure.
- * @n_params:      the number of parameters the procedure takes.
- * @n_return_vals: the number of return values the procedure returns.
- * @params:        the procedure's parameters.
- * @return_vals:   the procedure's return values.
+ * @name:                                      the procedure's name.
+ * @blurb:                                     a short text describing what the procedure does.
+ * @help:                                      the help text for the procedure (usually considerably
+ *                                             longer than @blurb).
+ * @author:                                    the procedure's author(s).
+ * @copyright:                                 the procedure's copyright.
+ * @date:                                      the date the procedure was added.
+ * @menu_label:                                the label to use for the procedure's menu entry,
+ *                                             or #NULL if the procedure has no menu entry.
+ * @image_types:                               the drawable types the procedure can handle.
+ * @type:                                      the type of the procedure.
+ * @n_params:                                  the number of parameters the procedure takes.
+ * @n_return_vals:                             the number of return values the procedure returns.
+ * @params: (array length=n_params):           the procedure's parameters.
+ * @return_vals: (array length=n_return_vals): the procedure's return values.
  *
  * Installs a new procedure with the PDB (procedural database).
  *
diff --git a/libgimp/gimp.h b/libgimp/gimp.h
index 43fc63b1e0..251376bac1 100644
--- a/libgimp/gimp.h
+++ b/libgimp/gimp.h
@@ -92,8 +92,8 @@ typedef void (* GimpQueryProc) (void);
  * @name: the name of the procedure which has been called.
  * @n_params: the number of parameters passed to the procedure.
  * @param: (array length=n_params): the parameters passed to @name.
- * @n_return_vals: the number of values returned by @name.
- * @return_vals: (array length=n_return_vals): the returned values.
+ * @n_return_vals: (out caller-allocates): the number of values returned by @name.
+ * @return_vals: (array length=n_return_vals) (out callee-allocates): the returned values.
  *
  * The run procedure is run during the lifetime of the GIMP session,
  * each time a plug-in procedure is called.