From ac4d1e2686fa6580f070b4aba9cd6423b691c7e3 Mon Sep 17 00:00:00 2001 From: Peter Eisenmann Date: Mon, 8 May 2023 01:24:25 +0200 Subject: docs: unify "dynamic memory needed" explanations All `_take` method constructors require dynamic memory, this unifies theses explanation texts. --- glib/garray.c | 30 ++++++++++++++++++++---------- glib/gbytes.c | 8 +++----- glib/gvariant.c | 5 +++-- 3 files changed, 26 insertions(+), 17 deletions(-) diff --git a/glib/garray.c b/glib/garray.c index 118360ca1..4e8c8c309 100644 --- a/glib/garray.c +++ b/glib/garray.c @@ -204,8 +204,10 @@ g_array_new (gboolean zero_terminated, * reference count of 1. * * This avoids having to copy the data manually, when it can just be - * inherited. @data will eventually be freed using g_free(), so must - * have been allocated with a suitable allocator. + * inherited. + * After this call, @data belongs to the #GArray and may no longer be + * modified by the caller. The memory of @data has to be dynamically + * allocated and will eventually be freed with g_free(). * * In case the elements need to be cleared when the array is freed, use * g_array_set_clear_func() to set a #GDestroyNotify function to perform @@ -252,8 +254,10 @@ g_array_new_take (gpointer data, * and setting the reference count to 1. * * This avoids having to copy the data manually, when it can just be - * inherited. @data will eventually be freed using g_free(), so must - * have been allocated with a suitable allocator. + * inherited. + * After this call, @data belongs to the #GArray and may no longer be + * modified by the caller. The memory of @data has to be dynamically + * allocated and will eventually be freed with g_free(). * * The length is calculated by iterating through @data until the first %NULL * element is found. @@ -1275,8 +1279,10 @@ g_ptr_array_new (void) * Creates a new #GPtrArray with @data as pointers, @len as length and a * reference count of 1. * - * This avoids having to copy such data manually. @data will eventually be - * freed using g_free(), so must have been allocated with a suitable allocator. + * This avoids having to copy such data manually. + * After this call, @data belongs to the #GPtrArray and may no longer be + * modified by the caller. The memory of @data has to be dynamically + * allocated and will eventually be freed with g_free(). * * It also sets @element_free_func for freeing each element when the array is * destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called @@ -1321,8 +1327,10 @@ g_ptr_array_new_take (gpointer *data, * Creates a new #GPtrArray with @data as pointers, computing the length of it * and setting the reference count to 1. * - * This avoids having to copy such data manually. @data will eventually be - * freed using g_free(), so must have been allocated with a suitable allocator. + * This avoids having to copy such data manually. + * After this call, @data belongs to the #GPtrArray and may no longer be + * modified by the caller. The memory of @data has to be dynamically + * allocated and will eventually be freed with g_free(). * * The length is calculated by iterating through @data until the first %NULL * element is found. @@ -2845,8 +2853,10 @@ g_byte_array_steal (GByteArray *array, * @data: (transfer full) (array length=len): byte data for the array * @len: length of @data * - * Create byte array containing the data. The data will be owned by the array - * and will be freed with g_free(), i.e. it could be allocated using g_strdup(). + * Creates a byte array containing the @data. + * After this call, @data belongs to the #GByteArray and may no longer be + * modified by the caller. The memory of @data has to be dynamically + * allocated and will eventually be freed with g_free(). * * Do not use it if @len is greater than %G_MAXUINT. #GByteArray * stores the length of its data in #guint, which may be shorter than diff --git a/glib/gbytes.c b/glib/gbytes.c index e4d269710..380e39f96 100644 --- a/glib/gbytes.c +++ b/glib/gbytes.c @@ -108,11 +108,9 @@ g_bytes_new (gconstpointer data, * * Creates a new #GBytes from @data. * - * After this call, @data belongs to the bytes and may no longer be - * modified by the caller. g_free() will be called on @data when the - * bytes is no longer in use. Because of this @data must have been created by - * a call to g_malloc(), g_malloc0() or g_realloc() or by one of the many - * functions that wrap these calls (such as g_new(), g_strdup(), etc). + * After this call, @data belongs to the #GBytes and may no longer be + * modified by the caller. The memory of @data has to be dynamically + * allocated and will eventually be freed with g_free(). * * For creating #GBytes with memory from other allocators, see * g_bytes_new_with_free_func(). diff --git a/glib/gvariant.c b/glib/gvariant.c index 40cda9c9d..b7e42413c 100644 --- a/glib/gvariant.c +++ b/glib/gvariant.c @@ -1282,8 +1282,9 @@ g_variant_new_string (const gchar *string) * @string must be valid UTF-8, and must not be %NULL. To encode * potentially-%NULL strings, use this with g_variant_new_maybe(). * - * This function consumes @string. g_free() will be called on @string - * when it is no longer required. + * After this call, @string belongs to the #GVariant and may no longer be + * modified by the caller. The memory of @data has to be dynamically + * allocated and will eventually be freed with g_free(). * * You must not modify or access @string in any other way after passing * it to this function. It is even possible that @string is immediately -- cgit v1.2.1