From 2da425ea5b974bc45388ad9ee65b1544d4bd2f66 Mon Sep 17 00:00:00 2001 From: Niels De Graef Date: Wed, 29 Dec 2021 19:08:22 +0100 Subject: [PATCH] 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: - * |[ + * + * ```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 - * gimp_file_procedure_set_format_name(). + * Returns the procedure's format name, as set with + * [method@FileProcedure.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 - * gimp_file_procedure_set_extensions(). + * Returns the procedure's extensions as set with + * [method@FileProcedure.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 - * gimp_file_procedure_set_magics(). + * Returns the procedure's magics as set with [method@FileProcedure.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 - * gimp_file_procedure_set_priority(). + * Returns the procedure's priority as set with + * [method@FileProcedure.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' flag as set with - * gimp_file_procedure_set_handles_remote(). + * Returns the procedure's 'handles remote' flags as set with + * [method@FileProcedure.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 - * gimp_load_procedure_set_handles_raw(). + * Returns the procedure's 'handles raw' flag as set with + * [method@GimpLoadProcedure.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 - * gimp_load_procedure_set_thumbnail_loader(). + * Returns the procedure's thumbnail loader procedure as set with + * [method@GimpLoadProcedure.set_thumbnail_loader]. + * + * Returns: The procedure's thumbnail loader procedure * * Since: 3.0 **/