From b99b56cc4405fa3ccabc87bcd518b49afb50a090 Mon Sep 17 00:00:00 2001 From: Jacob Boerema Date: Sat, 27 May 2023 17:20:12 -0400 Subject: [PATCH] libgimpbase: improve parasite API documentation (cherry picked from commit 640fb89f13ce3181918c7f5de2a34eeeec18d086) --- libgimpbase/gimpparasite.c | 5 ++++- libgimpbase/gimpparasite.h | 22 +++++++++++++++++++--- 2 files changed, 23 insertions(+), 4 deletions(-) diff --git a/libgimpbase/gimpparasite.c b/libgimpbase/gimpparasite.c index a813f258b9..afc955711c 100644 --- a/libgimpbase/gimpparasite.c +++ b/libgimpbase/gimpparasite.c @@ -207,7 +207,8 @@ gimp_parasite_print (GimpParasite *parasite) /** * gimp_parasite_new: * @name: the new #GimpParasite name. - * @flags: see libgimpbase/gimpparasite.h macros. + * @flags: see [const@Gimp.PARASITE_PERSISTENT] and [const@Gimp.PARASITE_UNDOABLE]; + * other values are mainly intended for internal use. * @size: the size of @data, including a terminal %NULL byte if needed. * @data: (nullable) (array length=size) (element-type char): the data to save in a parasite. * @@ -330,6 +331,8 @@ gimp_parasite_compare (const GimpParasite *a, * gimp_parasite_get_flags: * @parasite: a #GimpParasite * + * Get the flags of the parasite. + * * Returns: @parasite flags. */ gulong diff --git a/libgimpbase/gimpparasite.h b/libgimpbase/gimpparasite.h index f471976c18..de4dd92c22 100644 --- a/libgimpbase/gimpparasite.h +++ b/libgimpbase/gimpparasite.h @@ -55,8 +55,23 @@ GParamSpec * gimp_param_spec_parasite (const gchar *name, const gchar *blurb, GParamFlags flags); - +/** + * GIMP_PARASITE_PERSISTENT: + * + * A persistent parasite will be saved to XCF and can be used again after + * reloading. A non persistent parasite will only be available during the + * current session. + * See [struct@Gimp.Parasite]. + **/ #define GIMP_PARASITE_PERSISTENT 1 + +/** + * GIMP_PARASITE_UNDOABLE: + * + * An undoable parasite that was added, can be removed using the Undo action. + * If this flag is not set, undoing will not change the parasite. + * See [struct@Gimp.Parasite]. + **/ #define GIMP_PARASITE_UNDOABLE 2 #define GIMP_PARASITE_ATTACH_PARENT (0x80 << 8) @@ -71,9 +86,10 @@ GParamSpec * gimp_param_spec_parasite (const gchar *name, /** * GimpParasite: * @name: the parasite name, USE A UNIQUE PREFIX - * @flags: the parasite flags, like save in XCF etc. + * @flags: the parasite flags, see [const@Gimp.PARASITE_PERSISTENT] and + * [const@Gimp.PARASITE_UNDOABLE] * @size: the parasite size in bytes - * @data: (array length=size): the parasite data, the owner os the parasite is responsible + * @data: (array length=size): the parasite data, the owner of the parasite is responsible * for tracking byte order and internal structure **/ struct _GimpParasite