GNOME.org
 

[gimp] libgimp: Migrate gtk-doc annotations to gi-docgen

commit 2da425ea5b974bc45388ad9ee65b1544d4bd2f66
Author: Niels De Graef <nielsdegraef gmail com>
Date:   Wed Dec 29 19:08:22 2021 +0100

    libgimp: Migrate gtk-doc annotations to gi-docgen
    
    Move some of the documentation from the constructor to the class itself,
    so that it show up more prevalently.

 libgimp/gimpfileprocedure.c  | 98 ++++++++++++++++++++++++++------------------
 libgimp/gimpimageprocedure.c | 41 ++++++++++--------
 libgimp/gimploadprocedure.c  | 68 ++++++++++++++++--------------
 3 files changed, 120 insertions(+), 87 deletions(-)
---
diff --git a/libgimp/gimpfileprocedure.c b/libgimp/gimpfileprocedure.c
index 45798adf2e..0803bcb984 100644
--- a/libgimp/gimpfileprocedure.c
+++ b/libgimp/gimpfileprocedure.c
@@ -95,7 +95,7 @@ gimp_file_procedure_finalize (GObject *object)
 
 /**
  * gimp_file_procedure_set_format_name:
- * @procedure: A #GimpFileProcedure.
+ * @procedure: A file procedure.
  * @format_name: A public-facing name for the format, e.g. "PNG".
  *
  * Associates a format name with a file handler procedure.
@@ -106,9 +106,11 @@ gimp_file_procedure_finalize (GObject *object)
  *
  * Note that since the format name is public-facing, it is recommended
  * to localize it at runtime, for instance through gettext, like:
- * |[<!-- language="C" -->
+ *
+ * ```c
  * gimp_file_procedure_set_format_name (procedure, _("JPEG"));
- * ]|
+ * ```
+ *
  * Some language would indeed localize even some technical terms or
  * acronyms, even if sometimes just to rewrite them with the local
  * writing system.
@@ -127,10 +129,12 @@ gimp_file_procedure_set_format_name (GimpFileProcedure *procedure,
 
 /**
  * gimp_file_procedure_get_format_name:
- * @procedure: A #GimpFileProcedure.
+ * @procedure: A file procedure object.
+ *
+ * Returns the procedure's format name, as set with
+ * [method@FileProcedure.set_format_name].
  *
- * Returns: The procedure's format name as set with
- *          gimp_file_procedure_set_format_name().
+ * Returns: The procedure's format name.
  *
  * Since: 3.0
  **/
@@ -144,7 +148,7 @@ gimp_file_procedure_get_format_name (GimpFileProcedure *procedure)
 
 /**
  * gimp_file_procedure_set_mime_types:
- * @procedure: A #GimpFileProcedure.
+ * @procedure: A file procedure object.
  * @mime_types: A comma-separated list of MIME types, such as "image/jpeg".
  *
  * Associates MIME types with a file handler procedure.
@@ -170,10 +174,12 @@ gimp_file_procedure_set_mime_types (GimpFileProcedure *procedure,
 
 /**
  * gimp_file_procedure_get_mime_types:
- * @procedure: A #GimpFileProcedure.
+ * @procedure: A file procedure.
  *
- * Returns: The procedure's mime-type as set with
- *          gimp_file_procedure_set_mime_types().
+ * Returns the procedure's mime-type as set with
+ * [method@FileProcedure.set_mime_types].
+ *
+ * Returns: The procedure's registered mime-types.
  *
  * Since: 3.0
  **/
@@ -187,10 +193,13 @@ gimp_file_procedure_get_mime_types (GimpFileProcedure *procedure)
 
 /**
  * gimp_file_procedure_set_extensions:
- * @procedure:  A #GimpFileProcedure.
+ * @procedure:  A file procedure.
  * @extensions: A comma separated list of extensions this procedure can
  *              handle (i.e. "jpg,jpeg").
  *
+ * Registers the given list of extensions as something this procedure can
+ * handle.
+ *
  * Since: 3.0
  **/
 void
@@ -205,10 +214,12 @@ gimp_file_procedure_set_extensions (GimpFileProcedure *procedure,
 
 /**
  * gimp_file_procedure_get_extensions:
- * @procedure: A #GimpFileProcedure.
+ * @procedure: A file procedure object.
+ *
+ * Returns the procedure's extensions as set with
+ * [method@FileProcedure.set_extensions].
  *
- * Returns: The procedure's extensions as set with
- *          gimp_file_procedure_set_extensions().
+ * Returns: The procedure's registered extensions.
  *
  * Since: 3.0
  **/
@@ -222,7 +233,7 @@ gimp_file_procedure_get_extensions (GimpFileProcedure *procedure)
 
 /**
  * gimp_file_procedure_set_prefixes:
- * @procedure: A #GimpFileProcedure.
+ * @procedure: A file procedure object.
  * @prefixes:  A comma separated list of prefixes this procedure can
  *             handle (i.e. "http:,ftp:").
  *
@@ -243,10 +254,12 @@ gimp_file_procedure_set_prefixes (GimpFileProcedure *procedure,
 
 /**
  * gimp_file_procedure_get_prefixes:
- * @procedure: A #GimpFileProcedure.
+ * @procedure: A file procedure object.
  *
- * Returns: The procedure's prefixes as set with
- *          gimp_file_procedure_set_prefixes().
+ * Returns the procedure's prefixes as set with
+ * [method@FileProcedure.set_prefixes].
+ *
+ * Returns: The procedure's registered prefixes.
  *
  * Since: 3.0
  **/
@@ -260,9 +273,10 @@ gimp_file_procedure_get_prefixes (GimpFileProcedure *procedure)
 
 /**
  * gimp_file_procedure_set_magics:
- * @procedure: A #GimpFileProcedure.
- * @magics:    A comma separated list of magic file information this procedure
- *             can handle (i.e. "0,string,GIF").
+ * @procedure: A file procedure object.
+ * @magics:    A comma-separated list of magic file information (i.e. "0,string,GIF").
+ *
+ * Registers the list of magic file information this procedure can handle.
  *
  * Since: 3.0
  **/
@@ -278,10 +292,11 @@ gimp_file_procedure_set_magics (GimpFileProcedure *procedure,
 
 /**
  * gimp_file_procedure_get_magics:
- * @procedure: A #GimpFileProcedure.
+ * @procedure: A file procedure object.
+ *
+ * Returns the procedure's magics as set with [method@FileProcedure.set_magics].
  *
- * Returns: The procedure's magics as set with
- *          gimp_file_procedure_set_magics().
+ * Returns: The procedure's registered magics.
  *
  * Since: 3.0
  **/
@@ -295,14 +310,15 @@ gimp_file_procedure_get_magics (GimpFileProcedure *procedure)
 
 /**
  * gimp_file_procedure_set_priority:
- * @procedure: A #GimpFileProcedure.
+ * @procedure: A file procedure object.
  * @priority: The procedure's priority.
  *
- * Sets the priority of a file handler procedure. When more than one
- * procedure matches a given file, the procedure with the lowest
- * priority is used; if more than one procedure has the lowest
- * priority, it is unspecified which one of them is used. The default
- * priority for file handler procedures is 0.
+ * Sets the priority of a file handler procedure.
+ *
+ * When more than one procedure matches a given file, the procedure with the
+ * lowest priority is used; if more than one procedure has the lowest priority,
+ * it is unspecified which one of them is used. The default priority for file
+ * handler procedures is 0.
  *
  * Since: 3.0
  **/
@@ -317,10 +333,12 @@ gimp_file_procedure_set_priority (GimpFileProcedure *procedure,
 
 /**
  * gimp_file_procedure_get_priority:
- * @procedure: A #GimpFileProcedure.
+ * @procedure: A file procedure object.
+ *
+ * Returns the procedure's priority as set with
+ * [method@FileProcedure.set_priority].
  *
- * Returns: The procedure's priority as set with
- *          gimp_file_procedure_set_priority().
+ * Returns: The procedure's registered priority.
  *
  * Since: 3.0
  **/
@@ -344,9 +362,9 @@ gimp_file_procedure_get_priority (GimpFileProcedure *procedure)
  * #GFile passed that can point to a remote file.
  *
  * When @handles_remote is set to %FALSE, the procedure will get a
- * local #GFile passed and can use g_file_get_path() to get to a
- * filename that can be used with whatever non-GIO means of dealing
- * with the file.
+ * local [iface Gio File] passed and can use [method Gio File.get_path] to get
+ * to a filename that can be used with whatever non-GIO means of dealing with
+ * the file.
  *
  * Since: 3.0
  **/
@@ -361,10 +379,12 @@ gimp_file_procedure_set_handles_remote (GimpFileProcedure *procedure,
 
 /**
  * gimp_file_procedure_get_handles_remote:
- * @procedure: A #GimpFileProcedure.
+ * @procedure: A file procedure object.
+ *
+ * Returns the procedure's 'handles remote' flags as set with
+ * [method@FileProcedure.set_handles_remote].
  *
- * Returns: The procedure's 'handles remote' flag as set with
- *          gimp_file_procedure_set_handles_remote().
+ * Returns: The procedure's 'handles remote' flag
  *
  * Since: 3.0
  **/
diff --git a/libgimp/gimpimageprocedure.c b/libgimp/gimpimageprocedure.c
index 565d01e085..b26a3d2ef2 100644
--- a/libgimp/gimpimageprocedure.c
+++ b/libgimp/gimpimageprocedure.c
@@ -25,6 +25,26 @@
 #include "gimpimageprocedure.h"
 
 
+/**
+ * GimpImageProcedure:
+ *
+ * A [class@Procedure] subclass that makes it easier to write standard plug-in
+ * procedures that operate on drawables.
+ *
+ * It automatically adds the standard
+ *
+ * ( [enum@RunMode], [class@Image], [class@Drawable] )
+ *
+ * arguments of an image procedure. It is possible to add additional
+ * arguments.
+ *
+ * When invoked via [method Procedure run], it unpacks these standard
+ * arguments and calls @run_func which is a [callback@RunImageFunc]. The
+ * "args" [struct@ValueArray] of [callback@RunImageFunc] only contains
+ * additionally added arguments.
+ */
+
+
 struct _GimpImageProcedurePrivate
 {
   GimpRunImageFunc run_func;
@@ -206,28 +226,13 @@ gimp_image_procedure_set_sensitivity (GimpProcedure *procedure,
  * @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.
+ * @run_data: (closure run_func): user data passed to @run_func.
+ * @run_data_destroy: (destroy run_func) (nullable): free function for @run_data, or %NULL.
  *
  * Creates a new image procedure named @name which will call @run_func
  * when invoked.
  *
- * See gimp_procedure_new() for information about @proc_type.
- *
- * #GimpImageProcedure is a #GimpProcedure subclass that makes it easier
- * to write standard plug-in procedures that operate on drawables.
- *
- * It automatically adds the standard
- *
- * (#GimpRunMode, #GimpImage, #GimpDrawable)
- *
- * arguments of an image procedure. It is possible to add additional
- * arguments.
- *
- * When invoked via gimp_procedure_run(), it unpacks these standard
- * arguments and calls @run_func which is a #GimpRunImageFunc. The
- * "args" #GimpValueArray of #GimpRunImageFunc only contains
- * additionally added arguments.
+ * See [ctor Procedure new] for information about @proc_type.
  *
  * Returns: a new #GimpProcedure.
  *
diff --git a/libgimp/gimploadprocedure.c b/libgimp/gimploadprocedure.c
index 517f7828b4..09476dfe74 100644
--- a/libgimp/gimploadprocedure.c
+++ b/libgimp/gimploadprocedure.c
@@ -26,6 +26,30 @@
 #include "gimppdb_pdb.h"
 
 
+/**
+ * GimpLoadProcedure:
+ *
+ * A [class@Procedure] subclass that makes it easier to write file load
+ * procedures.
+ *
+ * It automatically adds the standard
+ *
+ * ( [enum@RunMode], [iface Gio File] )
+ *
+ * arguments and the standard
+ *
+ * ( [class@Image] )
+ *
+ * return value of a load procedure. It is possible to add additional
+ * arguments.
+ *
+ * When invoked via [method Procedure run], it unpacks these standard
+ * arguments and calls @run_func which is a [callback@RunImageFunc]. The
+ * "args" [struct@ValueArray] of [callback@RunImageFunc] only contains
+ * additionally added arguments.
+ */
+
+
 struct _GimpLoadProcedurePrivate
 {
   GimpRunLoadFunc  run_func;
@@ -218,26 +242,7 @@ gimp_load_procedure_create_config (GimpProcedure  *procedure,
  *
  * 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
- *
- * (#GimpRunMode, #GFile)
- *
- * arguments and the standard
- *
- * (#GimpImage)
- *
- * return value of a load procedure. It is possible to add additional
- * arguments.
- *
- * When invoked via gimp_procedure_run(), it unpacks these standard
- * arguments and calls @run_func which is a #GimpRunLoadFunc. The
- * "args" #GimpValueArray of #GimpRunLoadFunc only contains
- * additionally added arguments.
- *
- * Returns: a new #GimpProcedure.
+ * Returns: (transfer full): a new #GimpProcedure.
  *
  * Since: 3.0
  **/
@@ -272,11 +277,10 @@ gimp_load_procedure_new (GimpPlugIn      *plug_in,
 
 /**
  * gimp_load_procedure_set_handles_raw:
- * @procedure:   A #GimpLoadProcedure.
+ * @procedure:   A load procedure object.
  * @handles_raw: The procedure's handles raw flag.
  *
- * Registers a load loader procedure as capable of handling raw
- * digital camera loads.
+ * Registers a load procedure as capable of handling raw digital camera loads.
  *
  * Since: 3.0
  **/
@@ -291,10 +295,12 @@ gimp_load_procedure_set_handles_raw (GimpLoadProcedure *procedure,
 
 /**
  * gimp_load_procedure_get_handles_raw:
- * @procedure: A #GimpLoadProcedure.
+ * @procedure: A load procedure object.
+ *
+ * Returns the procedure's 'handles raw' flag as set with
+ * [method@GimpLoadProcedure.set_handles_raw].
  *
- * Returns: The procedure's handles raw flag as set with
- *          gimp_load_procedure_set_handles_raw().
+ * Returns: The procedure's 'handles raw' flag.
  *
  * Since: 3.0
  **/
@@ -308,7 +314,7 @@ gimp_load_procedure_get_handles_raw (GimpLoadProcedure *procedure)
 
 /**
  * gimp_load_procedure_set_thumbnail_loader:
- * @procedure:      A #GimpLoadProcedure.
+ * @procedure:      A load procedure object.
  * @thumbnail_proc: The name of the thumbnail load procedure.
  *
  * Associates a thumbnail loader with a file load procedure.
@@ -334,10 +340,12 @@ gimp_load_procedure_set_thumbnail_loader (GimpLoadProcedure *procedure,
 
 /**
  * gimp_load_procedure_get_thumbnail_loader:
- * @procedure: A #GimpLoadProcedure.
+ * @procedure: A load procedure object.
+ *
+ * Returns the procedure's thumbnail loader procedure as set with
+ * [method@GimpLoadProcedure.set_thumbnail_loader].
  *
- * Returns: The procedure's thumbnail loader procedure as set with
- *          gimp_load_procedure_set_thumbnail_loader().
+ * Returns: The procedure's thumbnail loader procedure
  *
  * Since: 3.0
  **/
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]