From 15aaaeaa507cfc252ead02296a576b014efa18b3 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Fri, 26 Apr 2019 12:47:19 +0100 Subject: [PATCH] docs: Expand introduction to boxed types Signed-off-by: Philip Withnall Fixes: #106 --- gobject/gboxed.c | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/gobject/gboxed.c b/gobject/gboxed.c index e4ebebeeb..c90bb480b 100644 --- a/gobject/gboxed.c +++ b/gobject/gboxed.c @@ -37,13 +37,24 @@ * @see_also: #GParamSpecBoxed, g_param_spec_boxed() * @title: Boxed Types * - * GBoxed is a generic wrapper mechanism for arbitrary C structures. The only - * thing the type system needs to know about the structures is how to copy and - * free them, beyond that they are treated as opaque chunks of memory. + * #GBoxed is a generic wrapper mechanism for arbitrary C structures. The only + * thing the type system needs to know about the structures is how to copy them + * (a #GBoxedCopyFunc) and how to free them (a #GBoxedFreeFunc) — beyond that + * they are treated as opaque chunks of memory. * * Boxed types are useful for simple value-holder structures like rectangles or - * points. They can also be used for wrapping structures defined in non-GObject - * based libraries. + * points. They can also be used for wrapping structures defined in non-#GObject + * based libraries. They allow arbitrary structures to be handled in a uniform + * way, allowing uniform copying (or referencing) and freeing (or unreferencing) + * of them, and uniform representation of the type of the contained structure. + * In turn, this allows any type which can be boxed to be set as the data in a + * #GValue, which allows for polymorphic handling of a much wider range of data + * types, and hence usage of such types as #GObject property values. + * + * #GBoxed is designed so that reference counted types can be boxed. Use the + * type’s ‘ref’ function as the #GBoxedCopyFunc, and its ‘unref’ function as the + * #GBoxedFreeFunc. For example, for #GBytes, the #GBoxedCopyFunc is + * g_bytes_ref(), and the #GBoxedFreeFunc is g_bytes_unref(). */ static inline void /* keep this function in sync with gvalue.c */