dnrops
/
gimp
mirror of https://github.com/GNOME/gimp.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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.
This commit is contained in:
Niels De Graef 2021-12-29 19:08:22 +01:00
parent 68ad641583
commit 2da425ea5b
3 changed files with 120 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
libgimp/gimpfileprocedure.c
View File

@ -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
* 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
**/

41
libgimp/gimpimageprocedure.c
View File

@ -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.
*

68
libgimp/gimploadprocedure.c
View File

@ -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
**/