@img/sharp-libvips-dev-wasm32 1.2.1 → 1.2.2-rc.2

package/include/aom/aom_decoder.h

@@ -52,7 +52,7 @@ extern "C" {
  *
  *  The available flags are specified by AOM_CODEC_CAP_* defines.
  */
-/*!brief Can support external frame buffers */
+/*!\brief Can support external frame buffers */
 #define AOM_CODEC_CAP_EXTERNAL_FRAME_BUFFER 0x200000
 
 /*! \brief Initialization-time Feature Enabling

package/include/aom/aom_encoder.h

@@ -377,6 +377,8 @@ typedef struct cfg_options {
 typedef long aom_enc_frame_flags_t;
 /*!\brief Force this frame to be a keyframe */
 #define AOM_EFLAG_FORCE_KF (1 << 0)
+/*!\brief Calculate PSNR for this frame, requires g_lag_in_frames to be 0 */
+#define AOM_EFLAG_CALCULATE_PSNR (1 << 1)
 
 /*!\brief Encoder configuration structure
  *

package/include/aom/aomcx.h

@@ -208,11 +208,11 @@ enum aome_enc_control_id {
    * encoding process, values greater than 0 will increase encoder speed at
    * the expense of quality.
    *
-   * Valid range: 0..11. 0 runs the slowest, and 11 runs the fastest;
+   * Valid range: 0..12. 0 runs the slowest, and 12 runs the fastest;
    * quality improves as speed decreases (since more compression
    * possibilities are explored).
    *
-   * NOTE: 10 and 11 are only allowed in AOM_USAGE_REALTIME. In
+   * NOTE: 10 - 12 are only allowed in AOM_USAGE_REALTIME. In
    * AOM_USAGE_GOOD_QUALITY and AOM_USAGE_ALL_INTRA, 9 is the highest allowed
    * value. However, AOM_USAGE_GOOD_QUALITY treats 7..9 the same as 6. Also,
    * AOM_USAGE_REALTIME treats 0..4 the same as 5.
@@ -313,6 +313,10 @@ enum aome_enc_control_id {
 
   /*!\brief Codec control function to set number of spatial layers, int
    * parameter
+   *
+   * Valid range:
+   *   \li When using #AV1E_SET_SVC_REF_FRAME_CONFIG: [1, #AOM_MAX_SS_LAYERS]
+   *   \li When \em not using #AV1E_SET_SVC_REF_FRAME_CONFIG: [1, 3]
    */
   AOME_SET_NUMBER_SPATIAL_LAYERS = 27,
 
@@ -1136,6 +1140,10 @@ enum aome_enc_control_id {
    * - 4 = use modulation for user rating based perceptual quality optimization
    * - 5 = use modulation for HDR video
    * - 6 = use modulation for all intra using Variance Boost
+   *
+   * \attention Delta q modes 1-5 are unsupported and are silently ignored in
+   * non-RD mode. Non-RD mode is enabled by setting cpu-used >= 8 (all intra
+   * usage) and cpu-used >= 7 (realtime usage).
    */
   AV1E_SET_DELTAQ_MODE = 107,
 
@@ -1399,7 +1407,8 @@ enum aome_enc_control_id {
    */
   AV1E_SET_SVC_REF_FRAME_COMP_PRED = 147,
 
-  /*!\brief Set --deltaq-mode strength.
+  /*!\brief Set --deltaq-mode strength, where the value is a percentage,
+   * unsigned int parameter.
    *
    * Valid range: [0, 1000]
    */
@@ -1578,6 +1587,36 @@ enum aome_enc_control_id {
    */
   AV1E_SET_MAX_CONSEC_FRAME_DROP_MS_CBR = 169,
 
+  /*!\brief Codec control to enable the low complexity decode mode, unsigned
+   * int parameter. Value of zero means this mode is disabled.
+   */
+  AV1E_SET_ENABLE_LOW_COMPLEXITY_DECODE = 170,
+
+  /*!\brief Codec control to set the screen content detection mode,
+   * aom_screen_detection_mode parameter.
+   *
+   * - 1: AOM_SCREEN_DETECTION_STANDARD = standard (default)
+   * - 2: AOM_SCREEN_DETECTION_ANTIALIASING_AWARE = anti-aliased text and
+   *   graphics aware
+   */
+  AV1E_SET_SCREEN_CONTENT_DETECTION_MODE = 171,
+
+  /*!\brief Codec control to enable adaptive sharpness, which modulates
+   * sharpness based on frame QP, unsigned int parameter.
+   *
+   * Adaptive sharpness helps mitigate blocking artifacts in the low to medium
+   * quality range.
+   *
+   * - 0 = disable (default)
+   * - 1 = enable
+   *
+   * \note When adaptive sharpness is enabled, AOME_SET_SHARPNESS acts as a
+   * "maximum sharpness" value. Adaptive sharpness can still modulate effective
+   * sharpness between 0 and the maximum sharpness. As a consequence, adaptive
+   * sharpness only has effects when sharpness is greater than 0.
+   */
+  AV1E_SET_ENABLE_ADAPTIVE_SHARPNESS = 172,
+
   // Any new encoder control IDs should be added above.
   // Maximum allowed encoder control ID is 229.
   // No encoder control ID should be added below.
@@ -1611,19 +1650,21 @@ typedef enum aom_scaling_mode_1d {
 /*!\brief  aom region of interest map
  *
  * These defines the data structures for the region of interest map
- *
- * TODO(yaowu): create a unit test for ROI map related APIs
- *
  */
 typedef struct aom_roi_map {
-  /*! An id between 0 and 7 for each 8x8 region within a frame. */
+  /*! If ROI is enabled. */
+  uint8_t enabled;
+  /*! An id between 0 and 7 for each 4x4 region within a frame. */
   unsigned char *roi_map;
-  unsigned int rows;              /**< Number of rows. */
-  unsigned int cols;              /**< Number of columns. */
-  int delta_q[AOM_MAX_SEGMENTS];  /**< Quantizer deltas. */
-  int delta_lf[AOM_MAX_SEGMENTS]; /**< Loop filter deltas. */
-  /*! Static breakout threshold for each segment. */
-  unsigned int static_threshold[AOM_MAX_SEGMENTS];
+  unsigned int rows;               /**< Number of rows. */
+  unsigned int cols;               /**< Number of columns. */
+  int delta_q[AOM_MAX_SEGMENTS];   /**< Quantizer deltas. */
+  int delta_lf[AOM_MAX_SEGMENTS];  /**< Loop filter deltas. */
+  int skip[AOM_MAX_SEGMENTS];      /**< Skip this block. */
+  int ref_frame[AOM_MAX_SEGMENTS]; /**< Reference frame for this block. */
+  int delta_qp_enabled;            /**< Delta qp feature enabled. */
+  int reference_enabled;           /**< Reference frame feature enabled. */
+  int rdmult_delta_qp;             /**< RD mult for delta qp feature. */
 } aom_roi_map_t;
 
 /*!\brief  aom active region map
@@ -1649,7 +1690,7 @@ typedef struct aom_scaling_mode {
   AOM_SCALING_MODE v_scaling_mode; /**< vertical scaling mode   */
 } aom_scaling_mode_t;
 
-/*!brief AV1 encoder content type */
+/*!\brief AV1 encoder content type */
 typedef enum {
   AOM_CONTENT_DEFAULT,
   AOM_CONTENT_SCREEN,
@@ -1657,7 +1698,15 @@ typedef enum {
   AOM_CONTENT_INVALID
 } aom_tune_content;
 
-/*!brief AV1 encoder timing info type signaling */
+/*!\brief Screen content detection mode */
+typedef enum {
+  /** Standard */
+  AOM_SCREEN_DETECTION_STANDARD = 1,
+  /** Anti-aliased text and graphics aware */
+  AOM_SCREEN_DETECTION_ANTIALIASING_AWARE = 2
+} aom_screen_detection_mode;
+
+/*!\brief AV1 encoder timing info type signaling */
 typedef enum {
   AOM_TIMING_UNSPECIFIED,
   AOM_TIMING_EQUAL,
@@ -1669,9 +1718,10 @@ typedef enum {
  * Changes the encoder to tune for certain types of input material.
  *
  * \note
- * AOM_TUNE_IQ is restricted to all intra mode (AOM_USAGE_ALL_INTRA). Setting
- * the tuning option to AOM_TUNE_IQ causes the following options to be set
- * (expressed as command-line options):
+ * AOM_TUNE_IQ and AOM_TUNE_SSIMULACRA2 are restricted to all intra mode
+ * (AOM_USAGE_ALL_INTRA). Setting the tuning option to either AOM_TUNE_IQ or
+ * AOM_TUNE_SSIMULACRA2 causes the following options to be set (expressed as
+ * command-line options):
  *   * --enable-qm=1
  *   * --qm-min=2
  *   * --qm-max=10
@@ -1680,6 +1730,9 @@ typedef enum {
  *   * --enable-cdef=3
  *   * --enable-chroma-deltaq=1
  *   * --deltaq-mode=6
+ *   * --screen-detection-mode=2
+ * AOM_TUNE_IQ additionally sets the following options:
+ *   * --enable-adaptive-sharpness=1
  */
 typedef enum {
   AOM_TUNE_PSNR = 0,
@@ -1698,6 +1751,12 @@ typedef enum {
    * the rdmult code with AOM_TUNE_SSIM.
    */
   AOM_TUNE_IQ = 10,
+/*!\brief Allows detection of the presence of AOM_TUNE_SSIMULACRA2 at compile
+ * time. */
+#define AOM_HAVE_TUNE_SSIMULACRA2 1
+  /* Tune that optimizes for maximum SSIMULACRA 2 scores. Shares the rdmult code
+     with AOM_TUNE_SSIM. */
+  AOM_TUNE_SSIMULACRA2 = 11,
 } aom_tune_metric;
 
 /*!\brief Distortion metric to use for RD optimization.
@@ -1721,21 +1780,33 @@ typedef enum {
 #define AOM_MAX_SS_LAYERS 4 /**< Max number of spatial layers */
 #define AOM_MAX_TS_LAYERS 8 /**< Max number of temporal layers */
 
-/*!brief Struct for spatial and temporal layer ID */
+/*!\brief Struct for spatial and temporal layer ID */
 typedef struct aom_svc_layer_id {
   int spatial_layer_id;  /**< Spatial layer ID */
   int temporal_layer_id; /**< Temporal layer ID */
 } aom_svc_layer_id_t;
 
-/*!brief Parameter type for SVC
+/*!\brief Parameter type for SVC
  *
  * In the arrays of size AOM_MAX_LAYERS, the index for spatial layer `sl` and
  * temporal layer `tl` is sl * number_temporal_layers + tl.
  *
  */
 typedef struct aom_svc_params {
-  int number_spatial_layers;                 /**< Number of spatial layers */
-  int number_temporal_layers;                /**< Number of temporal layers */
+  /*!Number of spatial layers
+   *
+   * Valid range:
+   *   \li When using #AV1E_SET_SVC_REF_FRAME_CONFIG: [1, #AOM_MAX_SS_LAYERS]
+   *   \li When \em not using #AV1E_SET_SVC_REF_FRAME_CONFIG: [1, 3]
+   */
+  int number_spatial_layers;
+  /*!Number of temporal layers
+   *
+   * Valid range:
+   *   \li When using #AV1E_SET_SVC_REF_FRAME_CONFIG: [1, #AOM_MAX_TS_LAYERS]
+   *   \li When \em not using #AV1E_SET_SVC_REF_FRAME_CONFIG: [1, 3]
+   */
+  int number_temporal_layers;
   int max_quantizers[AOM_MAX_LAYERS];        /**< Max Q for each layer */
   int min_quantizers[AOM_MAX_LAYERS];        /**< Min Q for each layer */
   int scaling_factor_num[AOM_MAX_SS_LAYERS]; /**< Scaling factor-numerator */
@@ -1746,7 +1817,7 @@ typedef struct aom_svc_params {
   int framerate_factor[AOM_MAX_TS_LAYERS];
 } aom_svc_params_t;
 
-/*!brief Parameters for setting ref frame config */
+/*!\brief Parameters for setting ref frame config */
 typedef struct aom_svc_ref_frame_config {
   // Three arrays need to be set: reference[], ref_id[], refresh[].
   // reference[i]: is a boolean flag to indicate which of the 7 possible
@@ -1769,14 +1840,14 @@ typedef struct aom_svc_ref_frame_config {
   int refresh[8]; /**< Refresh flag for each of the 8 buffer slots. */
 } aom_svc_ref_frame_config_t;
 
-/*!brief Parameters for setting ref frame compound prediction */
+/*!\brief Parameters for setting ref frame compound prediction */
 typedef struct aom_svc_ref_frame_comp_pred {
   // Use compound prediction for the ref_frame pairs GOLDEN_LAST (0),
   // LAST2_LAST (1), and ALTREF_LAST (2).
   int use_comp_pred[3]; /**<Compound reference flag. */
 } aom_svc_ref_frame_comp_pred_t;
 
-/*!brief Frame drop modes for spatial/quality layer SVC */
+/*!\brief Frame drop modes for spatial/quality layer SVC */
 typedef enum {
   AOM_LAYER_DROP,           /**< Any spatial layer can drop. */
   AOM_FULL_SUPERFRAME_DROP, /**< Only full superframe can drop. */
@@ -2279,6 +2350,16 @@ AOM_CTRL_USE_TYPE(AV1E_SET_POSTENCODE_DROP_RTC, int)
 AOM_CTRL_USE_TYPE(AV1E_SET_MAX_CONSEC_FRAME_DROP_MS_CBR, int)
 #define AOM_CTRL_AV1E_SET_MAX_CONSEC_FRAME_DROP_MS_CBR
 
+AOM_CTRL_USE_TYPE(AV1E_SET_ENABLE_LOW_COMPLEXITY_DECODE, unsigned int)
+#define AOM_CTRL_AV1E_SET_ENABLE_LOW_COMPLEXITY_DECODE
+
+AOM_CTRL_USE_TYPE(AV1E_SET_SCREEN_CONTENT_DETECTION_MODE,
+                  int) /* aom_screen_detection_mode */
+#define AOM_CTRL_SET_SCREEN_CONTENT_DETECTION_MODE
+
+AOM_CTRL_USE_TYPE(AV1E_SET_ENABLE_ADAPTIVE_SHARPNESS, unsigned int)
+#define AOM_CTRL_AV1E_SET_ENABLE_ADAPTIVE_SHARPNESS
+
 /*!\endcond */
 /*! @} - end defgroup aom_encoder */
 #ifdef __cplusplus

package/include/ffi.h

@@ -1,5 +1,5 @@
 /* -----------------------------------------------------------------*-C-*-
-   libffi 3.5.1
+   libffi 3.5.2
      - Copyright (c) 2011, 2014, 2019, 2021, 2022, 2024, 2025 Anthony Green
      - Copyright (c) 1996-2003, 2007, 2008 Red Hat, Inc.
 
@@ -316,8 +316,8 @@ size_t ffi_java_raw_size (ffi_cif *cif) __attribute__((deprecated));
 
 /* ---- Version API ------------------------------------------------------ */
 
-#define FFI_VERSION_STRING "3.5.1"
-#define FFI_VERSION_NUMBER 30501
+#define FFI_VERSION_STRING "3.5.2"
+#define FFI_VERSION_NUMBER 30502
 
 #ifndef LIBFFI_ASM
 /* Return a version string. */

package/include/ffitarget.h

@@ -42,14 +42,31 @@ typedef void (*ffi_fp)(void);
 
 typedef enum ffi_abi {
   FFI_FIRST_ABI = 0,
+#if __SIZEOF_POINTER__ == 4
   FFI_WASM32, // "raw", no structures, varargs, or closures (not implemented!)
   FFI_WASM32_EMSCRIPTEN, // structures, varargs, and split 64-bit params
+#elif __SIZEOF_POINTER__ == 8
+  FFI_WASM64,
+  FFI_WASM64_EMSCRIPTEN,
+#else
+#error "Unknown pointer size"
+#endif
   FFI_LAST_ABI,
+#if __SIZEOF_POINTER__ == 4
 #ifdef __EMSCRIPTEN__
   FFI_DEFAULT_ABI = FFI_WASM32_EMSCRIPTEN
 #else
   FFI_DEFAULT_ABI = FFI_WASM32
 #endif
+#elif __SIZEOF_POINTER__ == 8
+#ifdef __EMSCRIPTEN__
+  FFI_DEFAULT_ABI = FFI_WASM64_EMSCRIPTEN
+#else
+  FFI_DEFAULT_ABI = FFI_WASM64
+#endif
+#else
+#error "Unknown pointer size"
+#endif
 } ffi_abi;
 
 #define FFI_CLOSURES 1

package/include/glib-2.0/gio/gdbuserror.h

@@ -34,14 +34,15 @@ G_BEGIN_DECLS
 /**
  * G_DBUS_ERROR:
  *
- * Error domain for errors generated by a remote message bus. Errors
- * in this domain will be from the #GDBusError enumeration.  See
- * #GError for more information on error domains.
+ * Error domain for errors generated by a remote message bus.
+ *
+ * Errors in this domain will be from the [error@Gio.DBusError] enumeration.
+ * See [type@GLib.Error] for more information on error domains.
  *
  * Note that this error domain is intended only for
  * returning errors from a remote message bus process. Errors
- * generated locally in-process by e.g. #GDBusConnection should use the
- * %G_IO_ERROR domain.
+ * generated locally in-process (for example, by [class@Gio.DBusConnection])
+ * should use the [error@Gio.IOErrorEnum] domain.
  *
  * Since: 2.26
  */
@@ -60,10 +61,10 @@ gboolean g_dbus_error_strip_remote_error    (GError          *error);
 
 /**
  * GDBusErrorEntry:
- * @error_code: An error code.
- * @dbus_error_name: The D-Bus error name to associate with @error_code.
+ * @error_code: an error code
+ * @dbus_error_name: the D-Bus error name to associate with @error_code
  *
- * Struct used in g_dbus_error_register_error_domain().
+ * Struct used in [func@Gio.DBusError.register_error_domain].
  *
  * Since: 2.26
  */

package/include/glib-2.0/gio/ginetaddress.h

@@ -71,6 +71,12 @@ GInetAddress *        g_inet_address_new_from_bytes       (const guint8
 GIO_AVAILABLE_IN_ALL
 GInetAddress *        g_inet_address_new_loopback         (GSocketFamily         family);
 
+GIO_AVAILABLE_IN_2_86
+GInetAddress *        g_inet_address_new_from_bytes_with_ipv6_info (const guint8  *bytes,
+                                                                    GSocketFamily  family,
+                                                                    guint32        flowinfo,
+                                                                    guint32        scope_id);
+
 GIO_AVAILABLE_IN_ALL
 GInetAddress *        g_inet_address_new_any              (GSocketFamily         family);
 
@@ -120,6 +126,12 @@ gboolean              g_inet_address_get_is_mc_org_local  (GInetAddress
 GIO_AVAILABLE_IN_ALL
 gboolean              g_inet_address_get_is_mc_site_local (GInetAddress         *address);
 
+GIO_AVAILABLE_IN_2_86
+guint32               g_inet_address_get_scope_id         (GInetAddress         *address);
+
+GIO_AVAILABLE_IN_2_86
+guint32               g_inet_address_get_flowinfo         (GInetAddress         *address);
+
 G_END_DECLS
 
 #endif /* __G_INET_ADDRESS_H__ */

package/include/glib-2.0/gio/gioenums.h

@@ -987,13 +987,20 @@ typedef enum
  * @G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT: Allow another message bus connection to claim the name.
  * @G_BUS_NAME_OWNER_FLAGS_REPLACE: If another message bus connection owns the name and have
  * specified %G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT, then take the name from the other connection.
- * @G_BUS_NAME_OWNER_FLAGS_DO_NOT_QUEUE: If another message bus connection owns the name, immediately
- * return an error from g_bus_own_name() rather than entering the waiting queue for that name. (Since 2.54)
  *
  * Flags used in g_bus_own_name().
  *
  * Since: 2.26
  */
+/**
+ * G_BUS_NAME_OWNER_FLAGS_DO_NOT_QUEUE:
+ *
+ * If another message bus connection owns the name, immediately return an error
+ * from [func@Gio.bus_own_name] rather than entering the waiting queue for that
+ * name.
+ *
+ * Since: 2.54
+ **/
 typedef enum
 {
   G_BUS_NAME_OWNER_FLAGS_NONE = 0,                    /*< nick=none >*/

package/include/glib-2.0/glib/gstring.h

@@ -234,10 +234,10 @@ g_string_append_len_inline (GString    *gstring,
   else
     len_unsigned = (gsize) len;
 
-  if (G_LIKELY (gstring->len + len_unsigned < gstring->allocated_len))
+  if (G_LIKELY (len_unsigned < gstring->allocated_len - gstring->len))
     {
       char *end = gstring->str + gstring->len;
-      if (G_LIKELY (val + len_unsigned <= end || val > end + len_unsigned))
+      if (G_LIKELY (val + len_unsigned <= end || val >= end + len_unsigned))
         memcpy (end, val, len_unsigned);
       else
         memmove (end, val, len_unsigned);

package/include/glib-2.0/glib/gunicode.h

@@ -864,7 +864,7 @@ gchar   *g_utf8_truncate_middle   (const gchar *string,
                                    gsize        truncate_length);
 
 /* Find the UTF-8 character corresponding to ch, in string p. These
-   functions are equivalants to strchr and strrchr */
+   functions are equivalents to strchr and strrchr */
 GLIB_AVAILABLE_IN_ALL
 gchar* g_utf8_strchr  (const gchar *p,
                        gssize       len,

package/include/glib-2.0/gobject/glib-types.h

@@ -28,7 +28,7 @@
 
 G_BEGIN_DECLS
 
-/* A hack necesssary to preprocess this file with g-ir-scanner */
+/* A hack necessary to preprocess this file with g-ir-scanner */
 #ifdef __GI_SCANNER__
 typedef gsize GType;
 #endif

package/include/glib-2.0/gobject/gparam.h

@@ -412,7 +412,7 @@ GType	g_param_type_register_static	(const gchar		  *name,
 GOBJECT_AVAILABLE_IN_2_66
 gboolean g_param_spec_is_valid_name    (const gchar              *name);
 
-/* For registering builting types */
+/* For registering builtin types */
 GType  _g_param_type_register_static_constant (const gchar              *name,
 					       const GParamSpecTypeInfo *pspec_info,
 					       GType                     opt_type);

package/include/glib-2.0/gobject/gvalue.h

@@ -32,53 +32,61 @@ G_BEGIN_DECLS
 /* --- type macros --- */
 /**
  * G_TYPE_IS_VALUE:
- * @type: A #GType value.
+ * @type: a type
  * 
- * Checks whether the passed in type ID can be used for g_value_init().
+ * Checks whether the passed in type ID can be used for
+ * [method@GObject.Value.init].
  *
  * That is, this macro checks whether this type provides an implementation
- * of the #GTypeValueTable functions required for a type to create a #GValue of.
+ * of the [struct@GObject.TypeValueTable] functions required to be able to
+ * create a [struct@GObject.Value] instance.
  * 
- * Returns: Whether @type is suitable as a #GValue type.
+ * Returns: Whether @type is suitable as a [struct@GObject.Value] type.
  */
 #define	G_TYPE_IS_VALUE(type)		(g_type_check_is_value_type (type))
+
 /**
  * G_IS_VALUE:
- * @value: A #GValue structure.
+ * @value: a [struct@GObject.Value] structure
  * 
- * Checks if @value is a valid and initialized #GValue structure.
+ * Checks if @value is a valid and initialized [struct@GObject.Value] structure.
  *
- * Returns: %TRUE on success.
+ * Returns: true on success; false otherwise
  */
 #define	G_IS_VALUE(value)		(G_TYPE_CHECK_VALUE (value))
+
 /**
  * G_VALUE_TYPE:
- * @value: A #GValue structure.
+ * @value: a [struct@GObject.Value] structure
  *
  * Get the type identifier of @value.
  *
- * Returns: the #GType.
+ * Returns: the type ID
  */
 #define	G_VALUE_TYPE(value)		(((GValue*) (value))->g_type)
+
 /**
  * G_VALUE_TYPE_NAME:
- * @value: A #GValue structure.
+ * @value: a [struct@GObject.Value] structure
  *
- * Gets the type name of @value.
+ * Gets the name of the type of @value.
  *
- * Returns: the type name.
+ * Returns: the type name
  */
 #define	G_VALUE_TYPE_NAME(value)	(g_type_name (G_VALUE_TYPE (value)))
+
 /**
  * G_VALUE_HOLDS:
- * @value: A #GValue structure.
- * @type: A #GType value.
+ * @value: (not nullable): a [struct@GObject.Value] structure
+ * @type: a [type@GObject.Type]
  *
- * Checks if @value holds (or contains) a value of @type.
- * This macro will also check for @value != %NULL and issue a
+ * Checks if @value holds a value of @type.
+ *
+ * This macro will also check for `value != NULL` and issue a
  * warning if the check fails.
  *
- * Returns: %TRUE if @value holds the @type.
+ * Returns: true if @value is non-`NULL` and holds a value of the given @type;
+ *   false otherwise
  */
 #define G_VALUE_HOLDS(value,type)	(G_TYPE_CHECK_VALUE_TYPE ((value), (type)))
 
@@ -86,29 +94,39 @@ G_BEGIN_DECLS
 /* --- typedefs & structures --- */
 /**
  * GValueTransform:
- * @src_value: Source value.
- * @dest_value: Target value.
+ * @src_value: source value
+ * @dest_value: target value
  * 
  * The type of value transformation functions which can be registered with
- * g_value_register_transform_func().
+ * [func@GObject.Value.register_transform_func].
  *
  * @dest_value will be initialized to the correct destination type.
  */
 typedef void (*GValueTransform) (const GValue *src_value,
 				 GValue       *dest_value);
+
 /**
  * GValue:
  * 
  * An opaque structure used to hold different types of values.
  *
+ * Before it can be used, a `GValue` has to be initialized to a specific type by
+ * calling [method@GObject.Value.init] on it.
+ *
+ * Many types which are stored within a `GValue` need to allocate data on the
+ * heap, so [method@GObject.Value.unset] must always be called on a `GValue` to
+ * free any such data once you’re finished with the `GValue`, even if the
+ * `GValue` itself is stored on the stack.
+ *
  * The data within the structure has protected scope: it is accessible only
- * to functions within a #GTypeValueTable structure, or implementations of
- * the g_value_*() API. That is, code portions which implement new fundamental
- * types.
+ * to functions within a [struct@GObject.TypeValueTable] structure, or
+ * implementations of the `g_value_*()` API. That is, code which implements new
+ * fundamental types.
  *
- * #GValue users cannot make any assumptions about how data is stored
+ * `GValue` users cannot make any assumptions about how data is stored
  * within the 2 element @data union, and the @g_type member should
- * only be accessed through the G_VALUE_TYPE() macro.
+ * only be accessed through the [func@GObject.VALUE_TYPE] macro and related
+ * macros.
  */
 struct _GValue
 {
@@ -174,18 +192,32 @@ void	g_value_register_transform_func	(GType		 src_type,
 /**
  * G_VALUE_NOCOPY_CONTENTS:
  *
- * If passed to G_VALUE_COLLECT(), allocated data won't be copied
- * but used verbatim. This does not affect ref-counted types like
- * objects. This does not affect usage of g_value_copy(), the data will
+ * Flag to indicate that allocated data in a [struct@GObject.Value] shouldn’t be
+ * copied.
+ *
+ * If passed to [func@GObject.VALUE_COLLECT], allocated data won’t be copied
+ * but used verbatim. This does not affect ref-counted types like objects.
+ *
+ * This does not affect usage of [method@GObject.Value.copy]: the data will
  * be copied if it is not ref-counted.
+ *
+ * This flag should be checked by implementations of
+ * [callback@GObject.TypeValueFreeFunc], [callback@GObject.TypeValueCollectFunc]
+ * and [callback@GObject.TypeValueLCopyFunc].
  */
 #define G_VALUE_NOCOPY_CONTENTS (1 << 27)
 
 /**
  * G_VALUE_INTERNED_STRING:
  *
- * For string values, indicates that the string contained is canonical and will
- * exist for the duration of the process. See g_value_set_interned_string().
+ * Flag to indicate that a string in a [struct@GObject.Value] is canonical and
+ * will exist for the duration of the process.
+ *
+ * See [method@GObject.Value.set_interned_string].
+ *
+ * This flag should be checked by implementations of
+ * [callback@GObject.TypeValueFreeFunc], [callback@GObject.TypeValueCollectFunc]
+ * and [callback@GObject.TypeValueLCopyFunc].
  *
  * Since: 2.66
  */
@@ -194,13 +226,24 @@ void	g_value_register_transform_func	(GType		 src_type,
 /**
  * G_VALUE_INIT:
  *
- * A #GValue must be initialized before it can be used. This macro can
- * be used as initializer instead of an explicit `{ 0 }` when declaring
- * a variable, but it cannot be assigned to a variable.
+ * Clears a [struct@GObject.Value] to zero at declaration time.
+ *
+ * A [struct@GObject.Value] must be cleared and then initialized before it can
+ * be used. This macro can be assigned to a variable instead of an explicit
+ * `{ 0 }` when declaring it, but it cannot be assigned to a variable after
+ * declaration time.
  *
- * |[<!-- language="C" -->
+ * After the [struct@GObject.Value] is cleared, it must be initialized by
+ * calling [method@GObject.Value.init] on it before any other methods can be
+ * called on it.
+ *
+ * ```c
  *   GValue value = G_VALUE_INIT;
- * ]|
+ *
+ *   g_value_init (&value, SOME_G_TYPE);
+ *   …
+ *   g_value_unset (&value);
+ * ```
  *
  * Since: 2.30
  */