[gimp] libgimp: fix GimpPlugInClass methods introspection.

[Jehan <jehanp src gnome org>]

commit 183f00baf9d535594b243f0bebe412128082621b
Author: Jehan <jehan girinstud io>
Date:   Tue Sep 10 15:22:54 2019 +0200

    libgimp: fix GimpPlugInClass methods introspection.
    
    Commit 005143a43e66cfbda4be12294669c20dde3d5d6a completely broke all the
    introspected plug-ins, so I am reverting only the relevant changes.
    
    If some things need to be improved in this part of the docs, let's do it
    without breaking major stuff.
    In particular: abstract methods must be properly documented (with
    parameters, return values and annotations) like any function, and must
    be named Class::method, e.g. GimpPlugInClass::query_procedures.
    Other we break GObject Introspection, i.e. we break all plug-ins using
    these.

 libgimp/gimpplugin.h | 96 ++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 70 insertions(+), 26 deletions(-)
---
diff --git a/libgimp/gimpplugin.h b/libgimp/gimpplugin.h
index fdb3523b71..b2e38b2cb7 100644
--- a/libgimp/gimpplugin.h
+++ b/libgimp/gimpplugin.h
@@ -51,32 +51,11 @@ struct _GimpPlugIn
 
 /**
  * GimpPlugInClass:
- * @query_procedures: This method can be overridden by all plug-ins to
- *   return a newly allocated #GList of allocated strings naming the
- *   procedures registered by this plug-in. See documentation of
- *   #GimpPlugInClass.init_procedures() for differences.
- * @init_procedures: This method can be overridden by all plug-ins to
- *   return a newly allocated #GList of allocated strings naming
- *   procedures registered by this plug-in.
- *   It is different from #GimpPlugInClass.query_procedures() in that
- *   init happens at every startup, whereas query happens only once in
- *   the life of a plug-in (right after installation or update). Hence
- *   #GimpPlugInClass.init_procedures() typically returns procedures
- *   dependent to runtime conditions (such as the presence of a
- *   third-party tool), whereas #GimpPlugInClass.query_procedures()
- *   would usually return procedures that are always available
- *   unconditionally.
- *   Most of the time, you only want to override
- *   #GimpPlugInClass.query_procedures() and leave
- *   #GimpPlugInClass.init_procedures() untouched.
- * @create_procedure: This method must be overridden by all plug-ins
- *   and return a newly allocated #GimpProcedure named @name. It will
- *   be called for every @name as returned by
- *   #GimpPlugInClass.query_procedures() and
- *   #GimpPlugInClass.init_procedures() so care must be taken to handle
- *   them all.
- * @quit: This method can be overridden by a plug-in which needs to
- *   perform some actions upon quitting.
+ *
+ * A class which every plug-in should sublass, while overriding
+ * GimpPlugInClass::query_procedures() and/or
+ * GimpPlugInClass::init_procedures(), as well as
+ * GimpPlugInClass::create_procedure().
  *
  * Since: 3.0
  **/
@@ -84,12 +63,77 @@ struct _GimpPlugInClass
 {
   GObjectClass  parent_class;
 
+  /**
+   * GimpPlugInClass::query_procedures:
+   * @plug_in: a #GimpPlugIn.
+   *
+   * This method can be overridden by all plug-ins to return a newly
+   * allocated GList of allocated strings naming the procedures
+   * registered by this plug-in.
+   *
+   * See documentation of GimpPlugInClass::init_procedures() for
+   * differences.
+   *
+   * Returns: (element-type gchar*) (transfer full):
+   *          the names of the procedures registered by @plug_in.
+   *
+   * Since: 3.0
+   */
   GList          * (* query_procedures) (GimpPlugIn  *plug_in);
+
+  /**
+   * GimpPlugInClass::init_procedures:
+   * @plug_in: a #GimpPlugIn.
+   *
+   * This method can be overridden by all plug-ins to return a newly
+   * allocated #GList of allocated strings naming procedures registered
+   * by this plug-in.
+   *
+   * It is different from GimpPlugInClass::query_procedures() in that
+   * init happens at every startup, whereas query happens only once in
+   * the life of a plug-in (right after installation or update). Hence
+   * GimpPlugInClass::init_procedures() typically returns procedures
+   * dependent to runtime conditions (such as the presence of a
+   * third-party tool), whereas GimpPlugInClass::query_procedures()
+   * would usually return unconditional and always available
+   * procedures.  Most of the time, you only want to override
+   * GimpPlugInClass::query_procedures() and leave
+   * GimpPlugInClass::init_procedures() untouched.
+   *
+   * Returns: (element-type gchar*) (transfer full):
+   *          the names of the procedures registered by @plug_in.
+   *
+   * Since: 3.0
+   */
   GList          * (* init_procedures)  (GimpPlugIn  *plug_in);
 
+  /**
+   * GimpPlugInClass::create_procedure:
+   * @plug_in:        a #GimpPlugIn.
+   * @procedure_name: procedure name.
+   *
+   * This method should be overridden by all plug-ins and return a newly
+   * allocated #GimpProcedure named @name.
+   * It will be called for every @name as returned by query_procedures()
+   * and init_procedures() so care must be taken to handle them all.
+   *
+   * Returns: (transfer full):
+   *          the procedure to be registered by @plug_in.
+   *
+   * Since: 3.0
+   */
   GimpProcedure  * (* create_procedure) (GimpPlugIn  *plug_in,
                                          const gchar *procedure_name);
 
+  /**
+   * GimpPlugInClass::quit:
+   * @plug_in: a #GimpPlugIn.
+   *
+   * This method can be overridden by a plug-in which needs to perform
+   * some actions upon quitting.
+   *
+   * Since: 3.0
+   */
   void             (* quit)             (GimpPlugIn  *plug_in);
 
   /* Padding for future expansion */