[gimp] core: function documentation clarification
- From: Jehan <jehanp src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gimp] core: function documentation clarification
- Date: Mon, 24 May 2021 11:30:54 +0000 (UTC)
commit 203393a9fc9ff1e55406e411623a971f4797576e
Author: Stanislav Grinkov <43956-stanislavgrinkov users noreply gitlab gnome org>
Date: Fri May 7 22:55:04 2021 +0600
core: function documentation clarification
Update api documentation of GimpObject and GimpThumbnail classes to
clarify who and when will take care of disposing passed strings.
app/core/gimpobject.c | 31 +++++++++++++++++++++++++++++--
libgimpthumb/gimpthumbnail.c | 4 +++-
2 files changed, 32 insertions(+), 3 deletions(-)
---
diff --git a/app/core/gimpobject.c b/app/core/gimpobject.c
index 1a0a69e0c5..33cf55fd9c 100644
--- a/app/core/gimpobject.c
+++ b/app/core/gimpobject.c
@@ -209,7 +209,7 @@ gimp_object_get_property (GObject *object,
/**
* gimp_object_set_name:
* @object: a #GimpObject
- * @name: the @object's new name
+ * @name: the @object's new name (transfer none)
*
* Sets the @object's name. Takes care of freeing the old name and
* emitting the ::name_changed signal if the old and new name differ.
@@ -235,7 +235,7 @@ gimp_object_set_name (GimpObject *object,
/**
* gimp_object_set_name_safe:
* @object: a #GimpObject
- * @name: the @object's new name
+ * @name: the @object's new name (transfer none)
*
* A safe version of gimp_object_set_name() that takes care of
* handling newlines and overly long names. The actual name set
@@ -259,6 +259,19 @@ gimp_object_set_name_safe (GimpObject *object,
g_object_notify_by_pspec (G_OBJECT (object), object_props[PROP_NAME]);
}
+/**
+ * gimp_object_set_static_name:
+ * @object: a #GimpObject
+ * @name: the @object's new name as a static string
+ *
+ * Sets the @object's name.
+ * Takes care of freeing the old name (when it was not statically set)
+ * and emits the ::name_changed signal if the old and new name differ.
+ *
+ * This function is a variant of gimp_object_set_name() which assumes that
+ * the string is static and optimizes for this use case.
+ * Do not ever use this function with allocated strings.
+ **/
void
gimp_object_set_static_name (GimpObject *object,
const gchar *name)
@@ -277,6 +290,20 @@ gimp_object_set_static_name (GimpObject *object,
g_object_notify_by_pspec (G_OBJECT (object), object_props[PROP_NAME]);
}
+/**
+ * gimp_object_take_name:
+ * @object: a #GimpObject
+ * @name: the @object's new name (transfer full)
+ *
+ * Sets the @object's name. Takes care of freeing the old name and
+ * emitting the ::name_changed signal if the old and new name differ.
+ *
+ * Only use this function with GLib allocated strings.
+ *
+ * GimpObject will own the @name pointer and will dispose it when
+ * no longer needed or when it is the same as stored name.
+ * Calling code should *not* g_free() passed @name at all.
+ **/
void
gimp_object_take_name (GimpObject *object,
gchar *name)
diff --git a/libgimpthumb/gimpthumbnail.c b/libgimpthumb/gimpthumbnail.c
index 2f77cb0869..3ec9cd3eca 100644
--- a/libgimpthumb/gimpthumbnail.c
+++ b/libgimpthumb/gimpthumbnail.c
@@ -366,10 +366,12 @@ gimp_thumbnail_new (void)
/**
* gimp_thumbnail_set_uri:
* @thumbnail: a #GimpThumbnail object
- * @uri: an escaped URI
+ * @uri: an escaped URI (transfer none)
*
* Sets the location of the image file associated with the #thumbnail.
*
+ * Stores duplicate of passed @uri.
+ *
* All information stored in the #GimpThumbnail is reset.
**/
void
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]