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

docs: Migrate some gtk-doc comments to gi-docgen

This commit is contained in:
Niels De Graef 2021-12-29 11:21:19 +01:00
parent d5e22ad313
commit 0446a9025a
4 changed files with 146 additions and 146 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

157
libgimp/gimpprocedureconfig.c
View File

@ -28,21 +28,18 @@
/** /**
* SECTION: gimpprocedureconfig * GimpProcedureConfig:
* @title: GimpProcedureConfig
* @short_description: Config object for procedure arguments
* *
* #GimpProcedureConfig is the base class for #GimpProcedure specific * The base class for [class@Procedure] specific config objects and the main
* config objects and the main interface to manage aspects of * interface to manage aspects of [class@Procedure]'s arguments such as
* #GimpProcedure's arguments such as persistency of the last used * persistency of the last used arguments across GIMP sessions.
* arguments across GIMP sessions.
* *
* A #GimpProcedureConfig is created by a #GimpProcedure using * A procedure config is created by a [class@Procedure] using
* gimp_procedure_create_config() and its properties match the * [method@Procedure.create_config] and its properties match the
* procedure's arguments and auxiliary arguments in number, order and * procedure's arguments and auxiliary arguments in number, order and
* type. * type.
* *
* It implements the #GimpConfig interface and therefore has all its * It implements the [iface@Config] interface and therefore has all its
* serialization and deserialization features. * serialization and deserialization features.
* *
* Since: 3.0 * Since: 3.0
@ -202,12 +199,12 @@ gimp_procedure_config_get_property (GObject *object,
/** /**
* gimp_procedure_config_get_procedure: * gimp_procedure_config_get_procedure:
* @config: a #GimpProcedureConfig * @config: a procedure config
* *
* This function returns the #GimpProcedure which created @config, see * This function returns the [class@Procedure] which created @config, see
* gimp_procedure_create_config(). * [method@Procedure.create_config].
* *
* Returns: (transfer none): The #GimpProcedure which created @config. * Returns: (transfer none): The procedure which created this config.
* *
* Since: 3.0 * Since: 3.0
**/ **/
@ -230,8 +227,8 @@ gimp_procedure_config_get_procedure (GimpProcedureConfig *config)
* number, order and types of @config's properties. * number, order and types of @config's properties.
* *
* This function is meant to be used on @values which are passed as * This function is meant to be used on @values which are passed as
* arguments to the run() function of the #GimpProcedure which created * arguments to the run() function of the [class@Procedure] which created
* this @config. See gimp_procedure_create_config(). * this @config. See [method@Procedure.create_config].
* *
* Since: 3.0 * Since: 3.0
**/ **/
@ -275,7 +272,7 @@ gimp_procedure_config_set_values (GimpProcedureConfig *config,
* Gets the values from @config's properties and stores them in * Gets the values from @config's properties and stores them in
* @values. * @values.
* *
* See gimp_procedure_config_set_values(). * See [method@ProcedureConfig.set_values].
* *
* Since: 3.0 * Since: 3.0
**/ **/
@ -439,10 +436,10 @@ gimp_procedure_config_set_parasite (GimpProcedureConfig *config,
* gimp_procedure_config_begin_run: * gimp_procedure_config_begin_run:
* @config: a #GimpProcedureConfig * @config: a #GimpProcedureConfig
* @image: (nullable): a #GimpImage or %NULL * @image: (nullable): a #GimpImage or %NULL
* @run_mode: the #GimpRunMode passed to a #GimpProcedure's run() * @run_mode: the #GimpRunMode passed to a [class@Procedure]'s run()
* @args: the #GimpValueArray passed to a #GimpProcedure's run() * @args: the #GimpValueArray passed to a [class@Procedure]'s run()
* *
* Populates @config with values for a #GimpProcedure's run(), * Populates @config with values for a [class@Procedure]'s run(),
* depending on @run_mode. * depending on @run_mode.
* *
* If @run_mode is %GIMP_RUN_INTERACTIVE or %GIMP_RUN_WITH_LAST_VALS, * If @run_mode is %GIMP_RUN_INTERACTIVE or %GIMP_RUN_WITH_LAST_VALS,
@ -453,31 +450,29 @@ gimp_procedure_config_set_parasite (GimpProcedureConfig *config,
* values are found, the procedure's default argument values are used. * values are found, the procedure's default argument values are used.
* *
* If @run_mode is %GIMP_RUN_NONINTERACTIVE, the contents of @args are * If @run_mode is %GIMP_RUN_NONINTERACTIVE, the contents of @args are
* set on @config using gimp_procedure_config_set_values(). * set on @config using [method@ProcedureConfig.set_values].
* *
* After setting @config's properties like described above, arguments * After setting @config's properties like described above, arguments
* and auxiliary arguments are automatically synced from image * and auxiliary arguments are automatically synced from image
* parasites of the same name if they were set to * parasites of the same name if they were set to
* %GIMP_ARGUMENT_SYNC_PARASITE with * %GIMP_ARGUMENT_SYNC_PARASITE with [class@Procedure.set_argument_sync]:
* gimp_procedure_set_argument_sync():
* *
* String properties are set to the value of the image parasite if * String properties are set to the value of the image parasite if
* @run_mode is %GIMP_RUN_INTERACTIVE or %GIMP_RUN_WITH_LAST_VALS, or * @run_mode is %GIMP_RUN_INTERACTIVE or %GIMP_RUN_WITH_LAST_VALS, or
* if the corresponding argument is an auxiliary argument. As a * if the corresponding argument is an auxiliary argument. As a
* special case, a property named "gimp-comment" will default to * special case, a property named "gimp-comment" will default to
* gimp_get_default_comment() if there is no "gimp-comment" parasite. * [func@get_default_comment] if there is no "gimp-comment" parasite.
* *
* After calling this function, the @args passed to run() should be * After calling this function, the @args passed to run() should be
* left alone and @config be treated as the procedure's arguments. * left alone and @config be treated as the procedure's arguments.
* *
* It is possible to get @config's resulting values back into @args by * It is possible to get @config's resulting values back into @args by
* calling gimp_procedure_config_get_values(), as long as modified * calling [method@ProcedureConfig.get_values], as long as modified
* @args are written back to @config using * @args are written back to @config using [method@ProcedureConfig.set_values]
* gimp_procedure_config_set_values() before the call to * before the call to [method@ProcedureConfig.end_run].
* gimp_procedure_config_end_run().
* *
* This function should be used at the beginning of a procedure's * This function should be used at the beginning of a procedure's
* run() and be paired with a call to gimp_procedure_config_end_run() * run() and be paired with a call to [method@ProcedureConfig.end_run]
* at the end of run(). * at the end of run().
* *
* Since: 3.0 * Since: 3.0
@ -571,28 +566,28 @@ gimp_procedure_config_begin_run (GimpProcedureConfig *config,
/** /**
* gimp_procedure_config_end_run: * gimp_procedure_config_end_run:
* @config: a #GimpProcedureConfig * @config: a #GimpProcedureConfig
* @status: the return status of the #GimpProcedure's run() * @status: the return status of the [class@Procedure]'s run()
* *
* This function is the counterpart of * This function is the counterpart of
* gimp_procedure_config_begin_run() and must always be called in * [method@ProcedureConfig.begin_run] and must always be called in
* pairs in a procedure's run(), before returning return values. * pairs in a procedure's run(), before returning return values.
* *
* If the @run_mode passed to gimp_procedure_config_end_run() was * If the @run_mode passed to [method@ProcedureConfig.end_run] was
* %GIMP_RUN_INTERACTIVE, @config is saved as last used values to be * %GIMP_RUN_INTERACTIVE, @config is saved as last used values to be
* used when the procedure runs again. Additionally, if the #GimpImage * used when the procedure runs again. Additionally, if the #GimpImage
* passed to gimp_procedure_config_begin_run() was not %NULL, @config is * passed to [method@ProcedureConfig.begin_run] was not %NULL, @config is
* attached to @image as last used values for this image using a * attached to @image as last used values for this image using a
* #GimpParasite and gimp_image_attach_parasite(). * #GimpParasite and [method@Image.attach_parasite].
* *
* If @run_mode was not %GIMP_RUN_NONINTERACTIVE, this function also * If @run_mode was not %GIMP_RUN_NONINTERACTIVE, this function also
* conveniently calls gimp_displays_flush(), which is what most * conveniently calls [func@displays_flush], which is what most
* procedures want and doesn't do any harm if called redundantly. * procedures want and doesn't do any harm if called redundantly.
* *
* After a %GIMP_RUN_INTERACTIVE run, %GIMP_ARGUMENT_SYNC_PARASITE * After a %GIMP_RUN_INTERACTIVE run, %GIMP_ARGUMENT_SYNC_PARASITE
* values that have been changed are written back to their * values that have been changed are written back to their
* corresponding image parasite. * corresponding image parasite.
* *
* See gimp_procedure_config_begin_run(). * See [method@ProcedureConfig.begin_run].
* *
* Since: 3.0 * Since: 3.0
**/ **/
@ -657,55 +652,49 @@ gimp_procedure_config_end_run (GimpProcedureConfig *config,
/** /**
* gimp_procedure_config_begin_export: * gimp_procedure_config_begin_export:
* @config: a #GimpProcedureConfig * @config: a #GimpProcedureConfig
* @original_image: the #GimpImage passed to run() * @original_image: the image passed to run()
* @run_mode: the #GimpRunMode passed to a #GimpProcedure's run() * @run_mode: the #GimpRunMode passed to a [class@Procedure]'s run()
* @args: the #GimpValueArray passed to a #GimpProcedure's run() * @args: the value array passed to a [class@Procedure]'s run()
* @mime_type: (nullable): exported file format's mime type, or %NULL. * @mime_type: (nullable): exported file format's mime type, or %NULL.
* *
* This is a variant of gimp_procedure_config_begin_run() to be used * This is a variant of [method@ProcedureConfig.begin_run] to be used
* by file export procedures using #GimpSaveProcedure. It must be * by file export procedures using [class@SaveProcedure]. It must be
* paired with a call to gimp_procedure_config_end_export() at the end * paired with a call to [method@ProcedureConfig.end_export] at the end
* of run(). * of run().
* *
* It does everything gimp_procedure_config_begin_run() does but * It does everything [method@ProcedureConfig.begin_run] does but
* provides additional features to automate file export: * provides additional features to automate file export:
* *
* If @mime_type is non-%NULL, exporting metadata is handled * If @mime_type is non-%NULL, exporting metadata is handled
* automatically, by calling gimp_image_metadata_save_prepare() and * automatically, by calling [method@Image.metadata_save_prepare] and
* syncing its returned #GimpMetadataSaveFlags with @config's * syncing its returned [flags@MetadataSaveFlags] with @config's
* properties. (The corresponding gimp_image_metadata_save_finish() * properties. (The corresponding [method@Image.metadata_save_finish]
* will be called by gimp_procedure_config_end_export()). * will be called by [method@ProcedureConfig.end_export]).
* *
* The following boolean arguments of the used #GimpSaveProcedure are * The following boolean arguments of the used [class@SaveProcedure] are
* synced. The procedure can but must not provide these arguments. * synced. The procedure can but must not provide these arguments.
* *
* "save-exif" for %GIMP_METADATA_SAVE_EXIF. * - "save-exif" for %GIMP_METADATA_SAVE_EXIF.
* - "save-xmp" for %GIMP_METADATA_SAVE_XMP.
* - "save-iptc" for %GIMP_METADATA_SAVE_IPTC.
* - "save-thumbnail" for %GIMP_METADATA_SAVE_THUMBNAIL.
* - "save-color-profile" for %GIMP_METADATA_SAVE_COLOR_PROFILE.
* - "save-comment" for %GIMP_METADATA_SAVE_COMMENT.
* *
* "save-xmp" for %GIMP_METADATA_SAVE_XMP. * The values from the [flags@MetadataSaveFlags] will only ever be used
*
* "save-iptc" for %GIMP_METADATA_SAVE_IPTC.
*
* "save-thumbnail" for %GIMP_METADATA_SAVE_THUMBNAIL.
*
* "save-color-profile" for %GIMP_METADATA_SAVE_COLOR_PROFILE.
*
* "save-comment" for %GIMP_METADATA_SAVE_COMMENT.
*
* The values from the #GimpMetadataSaveFlags will only ever be used
* to set these properties to %FALSE, overriding the user's saved * to set these properties to %FALSE, overriding the user's saved
* default values for the procedure, but NOT overriding the last used * default values for the procedure, but NOT overriding the last used
* values from exporting @original_image or the last used values from * values from exporting @original_image or the last used values from
* exporting any other image using this procedure. * exporting any other image using this procedure.
* *
* If @mime_type is %NULL, #GimpMetadata handling is skipped. The * If @mime_type is %NULL, [class@Metadata] handling is skipped. The
* procedure can still have all of the above listed boolean arguments, * procedure can still have all of the above listed boolean arguments,
* but must take care of their default values itself. The easiest way * but must take care of their default values itself. The easiest way
* to do this is by simply using gimp_export_comment(), * to do this is by simply using [func@export_comment], [func@export_exif] etc.
* gimp_export_exif() etc. as default values for these arguments when * as default values for these arguments when adding them using
* adding them using GIMP_PROC_ARG_BOOLEAN() or * GIMP_PROC_ARG_BOOLEAN() or GIMP_PROC_AUX_ARG_BOOLEAN().
* GIMP_PROC_AUX_ARG_BOOLEAN().
* *
* Returns: (transfer none) (nullable): The #GimpMetadata to be used * Returns: (transfer none) (nullable): The metadata to be used
* for this export, or %NULL if @original_image doesn't have * for this export, or %NULL if @original_image doesn't have
* metadata. * metadata.
* *
@ -770,24 +759,24 @@ gimp_procedure_config_begin_export (GimpProcedureConfig *config,
/** /**
* gimp_procedure_config_end_export: * gimp_procedure_config_end_export:
* @config: a #GimpProcedureConfig * @config: a #GimpProcedureConfig
* @exported_image: the #GimpImage that was actually exported * @exported_image: the image that was actually exported
* @file: the #GFile @exported_image was written to * @file: the #GFile @exported_image was written to
* @status: the return status of the #GimpProcedure's run() * @status: the return status of the [class@Procedure]'s run()
* *
* This is a variant of gimp_procedure_config_end_run() to be used by * This is a variant of [method@ProcedureConfig.end_run] to be used by
* file export procedures using #GimpSaveProcedure. It must be paired * file export procedures using [class@SaveProcedure]. It must be paired
* with a call to gimp_procedure_config_begin_export() at the * with a call to [method@ProcedureConfig.begin_export] at the
* beginning of run(). * beginning of run().
* *
* It does everything gimp_procedure_config_begin_run() does but * It does everything [method@ProcedureConfig.begin_run] does but
* provides additional features to automate file export: * provides additional features to automate file export:
* *
* If @status is %GIMP_PDB_SUCCESS, and * If @status is %GIMP_PDB_SUCCESS, and
* gimp_procedure_config_begin_export() returned a #GimpMetadata, this * [method@ProcedureConfig.begin_export] returned a [class@Metadata], this
* function calls gimp_procedure_config_save_metadata(), which syncs * function calls [method@ProcedureConfig.save_metadata], which syncs
* back @config's export properties to the metadata's * back @config's export properties to the metadata's
* #GimpMetadataSaveFlags and writes metadata to @file using * [flags@MetadataSaveFlags] and writes metadata to @file using
* gimp_image_metadata_save_finish(). * [method@Image.metadata_save_finish].
* *
* Since: 3.0 * Since: 3.0
**/ **/
@ -817,23 +806,23 @@ gimp_procedure_config_end_export (GimpProcedureConfig *config,
/** /**
* gimp_procedure_config_save_metadata: * gimp_procedure_config_save_metadata:
* @config: a #GimpProcedureConfig * @config: a #GimpProcedureConfig
* @exported_image: the #GimpImage that was actually exported * @exported_image: the image that was actually exported
* @file: the #GFile @exported_image was written to * @file: the file @exported_image was written to
* *
* Note: There is normally no need to call this function because it's * Note: There is normally no need to call this function because it's
* already called from gimp_procedure_config_end_export(). * already called from [method@ProcedureConfig.end_export].
* *
* Only use this function if the #GimpMetadata returned by * Only use this function if the [class@Metadata] returned by
* gimp_procedure_config_begin_run() needs to be written at a specific * [method@ProcedureConfig.begin_run] needs to be written at a specific
* point of the export, other than its end. * point of the export, other than its end.
* *
* This function syncs back @config's export properties to the * This function syncs back @config's export properties to the
* metadata's #GimpMetadataSaveFlags and writes the metadata to @file * metadata's [flags@MetadataSaveFlags] and writes the metadata to @file
* using gimp_image_metadata_save_finish(). * using [method@Image.metadata_save_finish].
* *
* The metadata is only ever written once. If this function has been * The metadata is only ever written once. If this function has been
* called explicitly, it will do nothing when called a second time * called explicitly, it will do nothing when called a second time
* from gimp_procedure_config_end_export(). * from [method@ProcedureConfig.end_export].
* *
* Since: 3.0 * Since: 3.0
**/ **/

55
libgimp/gimpsaveprocedure.c
View File

@ -525,7 +525,9 @@ gimp_save_procedure_new (GimpPlugIn *plug_in,
* Determine whether @procedure supports saving Exif data. By default, * Determine whether @procedure supports saving Exif data. By default,
* it won't (so there is usually no reason to run this function with * it won't (so there is usually no reason to run this function with
* %FALSE). * %FALSE).
* This will have several consequence: *
* This will have several consequences:
*
* - Automatically adds a standard auxiliary argument "save-exif" in the * - Automatically adds a standard auxiliary argument "save-exif" in the
* end of the argument list of @procedure, with relevant blurb and * end of the argument list of @procedure, with relevant blurb and
* description. * description.
@ -535,11 +537,12 @@ gimp_save_procedure_new (GimpPlugIn *plug_in,
* - Generated GimpSaveProcedureDialog will contain the metadata * - Generated GimpSaveProcedureDialog will contain the metadata
* options, once again always in the same order and with consistent * options, once again always in the same order and with consistent
* GUI style across plug-ins. * GUI style across plug-ins.
* - API from #GimpProcedureConfig will automatically process these * - API from [class@ProcedureConfig] will automatically process these
* properties to decide whether to save a given metadata or not. * properties to decide whether to save a given metadata or not.
* *
* Note that since this is an auxiliary argument, it won't be part of * Note that since this is an auxiliary argument, it won't be part of
* the PDB arguments. By default, the value will be gimp_export_exif(). * the PDB arguments. By default, the value will be [func@export_exif].
*
* Since: 3.0 * Since: 3.0
**/ **/
void void
@ -561,7 +564,9 @@ gimp_save_procedure_set_support_exif (GimpSaveProcedure *procedure,
* Determine whether @procedure supports saving IPTC data. By default, * Determine whether @procedure supports saving IPTC data. By default,
* it won't (so there is usually no reason to run this function with * it won't (so there is usually no reason to run this function with
* %FALSE). * %FALSE).
* This will have several consequence: *
* This will have several consequences:
*
* - Automatically adds a standard auxiliary argument "save-iptc" in the * - Automatically adds a standard auxiliary argument "save-iptc" in the
* end of the argument list of @procedure, with relevant blurb and * end of the argument list of @procedure, with relevant blurb and
* description. * description.
@ -571,11 +576,12 @@ gimp_save_procedure_set_support_exif (GimpSaveProcedure *procedure,
* - Generated GimpSaveProcedureDialog will contain the metadata * - Generated GimpSaveProcedureDialog will contain the metadata
* options, once again always in the same order and with consistent * options, once again always in the same order and with consistent
* GUI style across plug-ins. * GUI style across plug-ins.
* - API from #GimpProcedureConfig will automatically process these * - API from [class@ProcedureConfig] will automatically process these
* properties to decide whether to save a given metadata or not. * properties to decide whether to save a given metadata or not.
* *
* Note that since this is an auxiliary argument, it won't be part of * Note that since this is an auxiliary argument, it won't be part of
* the PDB arguments. By default, the value will be gimp_export_iptc(). * the PDB arguments. By default, the value will be [func@export_iptc].
*
* Since: 3.0 * Since: 3.0
**/ **/
void void
@ -597,7 +603,9 @@ gimp_save_procedure_set_support_iptc (GimpSaveProcedure *procedure,
* Determine whether @procedure supports saving XMP data. By default, * Determine whether @procedure supports saving XMP data. By default,
* it won't (so there is usually no reason to run this function with * it won't (so there is usually no reason to run this function with
* %FALSE). * %FALSE).
* This will have several consequence: *
* This will have several consequences:
*
* - Automatically adds a standard auxiliary argument "save-xmp" in the * - Automatically adds a standard auxiliary argument "save-xmp" in the
* end of the argument list of @procedure, with relevant blurb and * end of the argument list of @procedure, with relevant blurb and
* description. * description.
@ -607,11 +615,12 @@ gimp_save_procedure_set_support_iptc (GimpSaveProcedure *procedure,
* - Generated GimpSaveProcedureDialog will contain the metadata * - Generated GimpSaveProcedureDialog will contain the metadata
* options, once again always in the same order and with consistent * options, once again always in the same order and with consistent
* GUI style across plug-ins. * GUI style across plug-ins.
* - API from #GimpProcedureConfig will automatically process these * - API from [class@ProcedureConfig] will automatically process these
* properties to decide whether to save a given metadata or not. * properties to decide whether to save a given metadata or not.
* *
* Note that since this is an auxiliary argument, it won't be part of * Note that since this is an auxiliary argument, it won't be part of
* the PDB arguments. By default, the value will be gimp_export_xmp(). * the PDB arguments. By default, the value will be [func@export_xmp].
*
* Since: 3.0 * Since: 3.0
**/ **/
void void
@ -633,7 +642,9 @@ gimp_save_procedure_set_support_xmp (GimpSaveProcedure *procedure,
* Determine whether @procedure supports saving ICC color profiles. By * Determine whether @procedure supports saving ICC color profiles. By
* default, it won't (so there is usually no reason to run this function * default, it won't (so there is usually no reason to run this function
* with %FALSE). * with %FALSE).
* This will have several consequence: *
* This will have several consequences:
*
* - Automatically adds a standard auxiliary argument * - Automatically adds a standard auxiliary argument
* "save-color-profile" in the end of the argument list of @procedure, * "save-color-profile" in the end of the argument list of @procedure,
* with relevant blurb and description. * with relevant blurb and description.
@ -643,12 +654,12 @@ gimp_save_procedure_set_support_xmp (GimpSaveProcedure *procedure,
* - Generated GimpSaveProcedureDialog will contain the metadata * - Generated GimpSaveProcedureDialog will contain the metadata
* options, once again always in the same order and with consistent * options, once again always in the same order and with consistent
* GUI style across plug-ins. * GUI style across plug-ins.
* - API from #GimpProcedureConfig will automatically process these * - API from [class@ProcedureConfig] will automatically process these
* properties to decide whether to save a given metadata or not. * properties to decide whether to save a given metadata or not.
* *
* Note that since this is an auxiliary argument, it won't be part of * Note that since this is an auxiliary argument, it won't be part of
* the PDB arguments. By default, the value will be * the PDB arguments. By default, the value will be [func@export_color_profile].
* gimp_export_color_profile(). *
* Since: 3.0 * Since: 3.0
**/ **/
void void
@ -670,7 +681,9 @@ gimp_save_procedure_set_support_profile (GimpSaveProcedure *procedure,
* Determine whether @procedure supports saving a thumbnail. By default, * Determine whether @procedure supports saving a thumbnail. By default,
* it won't (so there is usually no reason to run this function with * it won't (so there is usually no reason to run this function with
* %FALSE). * %FALSE).
* This will have several consequence: *
* This will have several consequences:
*
* - Automatically adds a standard auxiliary argument "save-thumbnail" * - Automatically adds a standard auxiliary argument "save-thumbnail"
* in the end of the argument list of @procedure, with relevant blurb * in the end of the argument list of @procedure, with relevant blurb
* and description. * and description.
@ -680,12 +693,13 @@ gimp_save_procedure_set_support_profile (GimpSaveProcedure *procedure,
* - Generated GimpSaveProcedureDialog will contain the metadata * - Generated GimpSaveProcedureDialog will contain the metadata
* options, once again always in the same order and with consistent * options, once again always in the same order and with consistent
* GUI style across plug-ins. * GUI style across plug-ins.
* - API from #GimpProcedureConfig will automatically process these * - API from [class@ProcedureConfig] will automatically process these
* properties to decide whether to save a given metadata or not. * properties to decide whether to save a given metadata or not.
* *
* Note that since this is an auxiliary argument, it won't be part of * Note that since this is an auxiliary argument, it won't be part of
* the PDB arguments. By default, the value will be * the PDB arguments. By default, the value will be
* gimp_export_thumbnail(). * [func@export_thumbnail].
*
* Since: 3.0 * Since: 3.0
**/ **/
void void
@ -707,7 +721,9 @@ gimp_save_procedure_set_support_thumbnail (GimpSaveProcedure *procedure,
* Determine whether @procedure supports saving a comment. By default, * Determine whether @procedure supports saving a comment. By default,
* it won't (so there is usually no reason to run this function with * it won't (so there is usually no reason to run this function with
* %FALSE). * %FALSE).
* This will have several consequence: *
* This will have several consequences:
*
* - Automatically adds a standard auxiliary argument "save-comment" * - Automatically adds a standard auxiliary argument "save-comment"
* in the end of the argument list of @procedure, with relevant blurb * in the end of the argument list of @procedure, with relevant blurb
* and description. * and description.
@ -717,12 +733,13 @@ gimp_save_procedure_set_support_thumbnail (GimpSaveProcedure *procedure,
* - Generated GimpSaveProcedureDialog will contain the metadata * - Generated GimpSaveProcedureDialog will contain the metadata
* options, once again always in the same order and with consistent * options, once again always in the same order and with consistent
* GUI style across plug-ins. * GUI style across plug-ins.
* - API from #GimpProcedureConfig will automatically process these * - API from [class@ProcedureConfig] will automatically process these
* properties to decide whether to save a given metadata or not. * properties to decide whether to save a given metadata or not.
* *
* Note that since this is an auxiliary argument, it won't be part of * Note that since this is an auxiliary argument, it won't be part of
* the PDB arguments. By default, the value will be * the PDB arguments. By default, the value will be
* gimp_export_comment(). * [func@export_comment].
*
* Since: 3.0 * Since: 3.0
**/ **/
void void

63
libgimpconfig/gimpconfig-iface.c
View File

@ -40,17 +40,10 @@
#include "libgimp/libgimp-intl.h" #include "libgimp/libgimp-intl.h"
/**
* SECTION: gimpconfig-iface
* @title: GimpConfig-iface
* @short_description: High-level API for libgimpconfig.
*
* High-level API for libgimpconfig.
**/
/* /*
* The GimpConfig serialization and deserialization interface. * GimpConfigIface:
*
* The [struct@Config] serialization and deserialization interface.
*/ */
@ -279,17 +272,17 @@ gimp_config_iface_copy (GimpConfig *src,
/** /**
* gimp_config_serialize_to_file: * gimp_config_serialize_to_file:
* @config: a #GObject that implements the #GimpConfigInterface. * @config: an object that implements [iface@ConfigInterface].
* @file: the #GFile to write the configuration to. * @file: the file to write the configuration to.
* @header: optional file header (must be ASCII only) * @header: (nullable): optional file header (must be ASCII only)
* @footer: optional file footer (must be ASCII only) * @footer: (nullable): optional file footer (must be ASCII only)
* @data: user data passed to the serialize implementation. * @data: user data passed to the serialize implementation.
* @error: return location for a possible error * @error: return location for a possible error
* *
* Serializes the object properties of @config to the file specified * Serializes the object properties of @config to the file specified
* by @file. If a file with that name already exists, it is * by @file. If a file with that name already exists, it is
* overwritten. Basically this function opens @file for you and calls * overwritten. Basically this function opens @file for you and calls
* the serialize function of the @config's #GimpConfigInterface. * the serialize function of the @config's [iface@ConfigInterface].
* *
* Returns: %TRUE if serialization succeeded, %FALSE otherwise. * Returns: %TRUE if serialization succeeded, %FALSE otherwise.
* *
@ -320,17 +313,17 @@ gimp_config_serialize_to_file (GimpConfig *config,
/** /**
* gimp_config_serialize_to_stream: * gimp_config_serialize_to_stream:
* @config: a #GObject that implements the #GimpConfigInterface. * @config: an object that implements [iface@ConfigInterface].
* @output: the #GOutputStream to write the configuration to. * @output: the #GOutputStream to write the configuration to.
* @header: optional file header (must be ASCII only) * @header: (nullable): optional file header (must be ASCII only)
* @footer: optional file footer (must be ASCII only) * @footer: (nullable): optional file footer (must be ASCII only)
* @data: user data passed to the serialize implementation. * @data: user data passed to the serialize implementation.
* @error: return location for a possible error * @error: return location for a possible error
* *
* Serializes the object properties of @config to the stream specified * Serializes the object properties of @config to the stream specified
* by @output. * by @output.
* *
* Returns: %TRUE if serialization succeeded, %FALSE otherwise. * Returns: Whether serialization succeeded.
* *
* Since: 2.10 * Since: 2.10
**/ **/
@ -359,7 +352,7 @@ gimp_config_serialize_to_stream (GimpConfig *config,
/** /**
* gimp_config_serialize_to_fd: * gimp_config_serialize_to_fd:
* @config: a #GObject that implements the #GimpConfigInterface. * @config: an object that implements [iface@ConfigInterface].
* @fd: a file descriptor, opened for writing * @fd: a file descriptor, opened for writing
* @data: user data passed to the serialize implementation. * @data: user data passed to the serialize implementation.
* *
@ -391,7 +384,7 @@ gimp_config_serialize_to_fd (GimpConfig *config,
/** /**
* gimp_config_serialize_to_string: * gimp_config_serialize_to_string:
* @config: a #GObject that implements the #GimpConfigInterface. * @config: an object that implements the [iface@ConfigInterface].
* @data: user data passed to the serialize implementation. * @data: user data passed to the serialize implementation.
* *
* Serializes the object properties of @config to a string. * Serializes the object properties of @config to a string.
@ -421,14 +414,14 @@ gimp_config_serialize_to_string (GimpConfig *config,
/** /**
* gimp_config_serialize_to_parasite: * gimp_config_serialize_to_parasite:
* @config: a #GObject that implements the #GimpConfigInterface. * @config: an object that implements the [iface@ConfigInterface].
* @parasite_name: the new parasite's name * @parasite_name: the new parasite's name
* @parasite_flags: the new parasite's flags * @parasite_flags: the new parasite's flags
* @data: user data passed to the serialize implementation. * @data: user data passed to the serialize implementation.
* *
* Serializes the object properties of @config to a #GimpParasite. * Serializes the object properties of @config to a [class@Parasite].
* *
* Returns: (transfer full): the newly allocated #GimpParasite. * Returns: (transfer full): the newly allocated parasite.
* *
* Since: 3.0 * Since: 3.0
**/ **/
@ -461,17 +454,17 @@ gimp_config_serialize_to_parasite (GimpConfig *config,
/** /**
* gimp_config_deserialize_file: * gimp_config_deserialize_file:
* @config: a #GObject that implements the #GimpConfigInterface. * @config: an oObject that implements the #GimpConfigInterface.
* @file: the #GFile to read configuration from. * @file: the file to read configuration from.
* @data: user data passed to the deserialize implementation. * @data: user data passed to the deserialize implementation.
* @error: return location for a possible error * @error: return location for a possible error
* *
* Opens the file specified by @file, reads configuration data from it * Opens the file specified by @file, reads configuration data from it
* and configures @config accordingly. Basically this function creates * and configures @config accordingly. Basically this function creates
* a properly configured #GScanner for you and calls the deserialize * a properly configured [struct@GLib.Scanner] for you and calls the deserialize
* function of the @config's #GimpConfigInterface. * function of the @config's [iface@ConfigInterface].
* *
* Returns: %TRUE if deserialization succeeded, %FALSE otherwise. * Returns: Whether deserialization succeeded.
* *
* Since: 2.10 * Since: 2.10
**/ **/
@ -509,8 +502,8 @@ gimp_config_deserialize_file (GimpConfig *config,
/** /**
* gimp_config_deserialize_stream: * gimp_config_deserialize_stream:
* @config: a #GObject that implements the #GimpConfigInterface. * @config: an object that implements the #GimpConfigInterface.
* @input: the #GInputStream to read configuration from. * @input: the input stream to read configuration from.
* @data: user data passed to the deserialize implementation. * @data: user data passed to the deserialize implementation.
* @error: return location for a possible error * @error: return location for a possible error
* *
@ -519,7 +512,7 @@ gimp_config_deserialize_file (GimpConfig *config,
* #GScanner for you and calls the deserialize function of the * #GScanner for you and calls the deserialize function of the
* @config's #GimpConfigInterface. * @config's #GimpConfigInterface.
* *
* Returns: %TRUE if deserialization succeeded, %FALSE otherwise. * Returns: Whether deserialization succeeded.
* *
* Since: 2.10 * Since: 2.10
**/ **/
@ -687,13 +680,13 @@ gimp_config_deserialize_return (GScanner *scanner,
/** /**
* gimp_config_serialize: * gimp_config_serialize:
* @config: a #GObject that implements the #GimpConfigInterface. * @config: an object that implements the #GimpConfigInterface.
* @writer: the #GimpConfigWriter to use. * @writer: the #GimpConfigWriter to use.
* @data: client data * @data: client data
* *
* Serialize the #GimpConfig object. * Serialize the #GimpConfig object.
* *
* Returns: %TRUE if serialization succeeded, %FALSE otherwise. * Returns: Whether serialization succeeded.
* *
* Since: 2.8 * Since: 2.8
**/ **/
@ -716,7 +709,7 @@ gimp_config_serialize (GimpConfig *config,
* *
* Deserialize the #GimpConfig object. * Deserialize the #GimpConfig object.
* *
* Returns: %TRUE if deserialization succeeded, %FALSE otherwise. * Returns: Whether serialization succeeded.
* *
* Since: 2.8 * Since: 2.8
**/ **/

17
libgimpmodule/gimpmodule.h
View File

@ -116,31 +116,32 @@ struct _GimpModuleInfo
/** /**
* GimpModuleQueryFunc: * GimpModuleQueryFunc:
* @module: The #GimpModule responsible for this loadable module. * @module: The module responsible for this loadable module.
* @Returns: The #GimpModuleInfo struct describing the module.
* *
* The signature of the query function a loadable GIMP module must * The signature of the query function a loadable GIMP module must
* implement. In the module, the function must be called * implement. In the module, the function must be called [func@Module.query].
* gimp_module_query().
* *
* #GimpModule will copy the returned #GimpModuleInfo struct, so the * [class@Module] will copy the returned [struct@ModuleInfo], so the
* module doesn't need to keep these values around (however in most * module doesn't need to keep these values around (however in most
* cases the module will just return a pointer to a constant * cases the module will just return a pointer to a constant
* structure). * structure).
*
* Returns: The info struct describing the module.
**/ **/
typedef const GimpModuleInfo * (* GimpModuleQueryFunc) (GTypeModule *module); typedef const GimpModuleInfo * (* GimpModuleQueryFunc) (GTypeModule *module);
/** /**
* GimpModuleRegisterFunc: * GimpModuleRegisterFunc:
* @module: The #GimpModule responsible for this loadable module. * @module: The module responsible for this loadable module.
* @Returns: %TRUE on success, %FALSE otherwise.
* *
* The signature of the register function a loadable GIMP module must * The signature of the register function a loadable GIMP module must
* implement. In the module, the function must be called * implement. In the module, the function must be called
* gimp_module_register(). * [func@Module.register].
* *
* When this function is called, the module should register all the types * When this function is called, the module should register all the types
* it implements with the passed @module. * it implements with the passed @module.
*
* Returns: Whether the registration was succesfull
**/ **/
typedef gboolean (* GimpModuleRegisterFunc) (GTypeModule *module); typedef gboolean (* GimpModuleRegisterFunc) (GTypeModule *module);