From 27f5e96604763535be0213ee218f4ca7676bc410 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sun, 21 Mar 2021 12:45:56 +0000 Subject: docs: Update pixdata style --- gdk-pixbuf/gdk-pixdata.c | 117 +++++++++++++++++++++++++---------------------- 1 file changed, 63 insertions(+), 54 deletions(-) (limited to 'gdk-pixbuf') diff --git a/gdk-pixbuf/gdk-pixdata.c b/gdk-pixbuf/gdk-pixdata.c index 35f90dffc..621167611 100644 --- a/gdk-pixbuf/gdk-pixdata.c +++ b/gdk-pixbuf/gdk-pixdata.c @@ -202,20 +202,24 @@ get_uint32 (const guint8 *stream, guint *result) * @stream_length: length of the stream used for deserialization. * @stream: (array length=stream_length): stream of bytes containing a * serialized #GdkPixdata structure. - * @error: #GError location to indicate failures (maybe %NULL to ignore errors). + * @error: #GError location to indicate failures (maybe `NULL` to ignore errors). * * Deserializes (reconstruct) a #GdkPixdata structure from a byte stream. + * * The byte stream consists of a straightforward writeout of the - * #GdkPixdata fields in network byte order, plus the @pixel_data + * `GdkPixdata` fields in network byte order, plus the `pixel_data` * bytes the structure points to. - * The @pixdata contents are reconstructed byte by byte and are checked - * for validity. This function may fail with %GDK_PIXBUF_ERROR_CORRUPT_IMAGE - * or %GDK_PIXBUF_ERROR_UNKNOWN_TYPE. * - * Return value: Upon successful deserialization %TRUE is returned, - * %FALSE otherwise. + * The `pixdata` contents are reconstructed byte by byte and are checked + * for validity. * - * Deprecated: 2.32: Use #GResource instead. + * This function may fail with `GDK_PIXBUF_ERROR_CORRUPT_IMAGE` + * or `GDK_PIXBUF_ERROR_UNKNOWN_TYPE`. + * + * Return value: Upon successful deserialization `TRUE` is returned, + * `FALSE` otherwise. + * + * Deprecated: 2.32: Use `GResource` instead. **/ gboolean gdk_pixdata_deserialize (GdkPixdata *pixdata, @@ -333,17 +337,18 @@ free_buffer (guchar *pixels, gpointer data) /** * gdk_pixdata_from_pixbuf: (skip) - * @pixdata: a #GdkPixdata to fill. - * @pixbuf: the data to fill @pixdata with. + * @pixdata: a `GdkPixdata` to fill. + * @pixbuf: the data to fill `pixdata` with. * @use_rle: whether to use run-length encoding for the pixel data. * - * Converts a #GdkPixbuf to a #GdkPixdata. If @use_rle is %TRUE, the - * pixel data is run-length encoded into newly-allocated memory and a - * pointer to that memory is returned. + * Converts a `GdkPixbuf` to a `GdkPixdata`. + * + * If `use_rle` is `TRUE`, the pixel data is run-length encoded into + * newly-allocated memory and a pointer to that memory is returned. * - * Returns: (nullable): If @use_rle is %TRUE, a pointer to the - * newly-allocated memory for the run-length encoded pixel data, - * otherwise %NULL. + * Returns: (nullable) (array) (element-type guint8): If `use_rle` is + * `TRUE`, a pointer to the newly-allocated memory for the run-length + * encoded pixel data, otherwise `NULL`. * * Deprecated: 2.32: Use #GResource instead. **/ @@ -432,17 +437,20 @@ gdk_pixdata_from_pixbuf (GdkPixdata *pixdata, /** * gdk_pixbuf_from_pixdata: - * @pixdata: a #GdkPixdata to convert into a #GdkPixbuf. + * @pixdata: a #GdkPixdata to convert into a `GdkPixbuf`. * @copy_pixels: whether to copy raw pixel data; run-length encoded - * pixel data is always copied. + * pixel data is always copied. * @error: location to store possible errors. * - * Converts a #GdkPixdata to a #GdkPixbuf. If @copy_pixels is %TRUE or - * if the pixel data is run-length-encoded, the pixel data is copied into - * newly-allocated memory; otherwise it is reused. + * Converts a `GdkPixdata` to a `GdkPixbuf`. * - * Returns: (transfer full): a new #GdkPixbuf. - * Deprecated: 2.32: Use #GResource instead. + * If `copy_pixels` is `TRUE` or if the pixel data is run-length-encoded, + * the pixel data is copied into newly-allocated memory; otherwise it is + * reused. + * + * Returns: (transfer full): a new pixbuf + * + * Deprecated: 2.32: Use `GResource` instead. **/ GdkPixbuf* gdk_pixbuf_from_pixdata (const GdkPixdata *pixdata, @@ -702,20 +710,19 @@ save_rle_decoder (GString *gstring, /** * gdk_pixdata_to_csource: - * @pixdata: a #GdkPixdata to convert to C source. - * @name: used for naming generated data structures or macros. - * @dump_type: a #GdkPixdataDumpType determining the kind of C - * source to be generated. + * @pixdata: a `GdkPixdata` to convert to C source + * @name: used for naming generated data structures or macros + * @dump_type: the kind of C source to be generated * * Generates C source code suitable for compiling images directly * into programs. * - * gdk-pixbuf ships with a program called - * [gdk-pixbuf-csource][gdk-pixbuf-csource], which offers a command - * line interface to this function. + * GdkPixbuf ships with a program called `gdk-pixbuf-csource`, which offers + * a command line interface to this function. + * + * Returns: (transfer full): a newly-allocated string buffer containing + * the C source form of `pixdata`. * - * Returns: a newly-allocated string containing the C source form - * of @pixdata. * Deprecated: 2.32: Use #GResource instead. **/ GString* @@ -943,49 +950,51 @@ gdk_pixdata_to_csource (GdkPixdata *pixdata, /** * gdk_pixbuf_new_from_inline: - * @data_length: Length in bytes of the @data argument or -1 to - * disable length checks + * @data_length: Length in bytes of the `data` argument or -1 to + * disable length checks * @data: (array length=data_length): Byte data containing a - * serialized #GdkPixdata structure + * serialized `GdkPixdata` structure * @copy_pixels: Whether to copy the pixel data, or use direct pointers - * @data for the resulting pixbuf - * @error: #GError return location, may be %NULL to ignore errors + * `data` for the resulting pixbuf + * @error: #GError return location, may be `NULL` to ignore errors + * + * Creates a `GdkPixbuf` from a flat representation that is suitable for + * storing as inline data in a program. * - * Create a #GdkPixbuf from a flat representation that is suitable for - * storing as inline data in a program. This is useful if you want to - * ship a program with images, but don't want to depend on any - * external files. + * This is useful if you want to ship a program with images, but don't want + * to depend on any external files. + * + * GdkPixbuf ships with a program called `gdk-pixbuf-csource`, which allows + * for conversion of `GdkPixbuf`s into such a inline representation. * - * gdk-pixbuf ships with a program called [gdk-pixbuf-csource][gdk-pixbuf-csource], - * which allows for conversion of #GdkPixbufs into such a inline representation. * In almost all cases, you should pass the `--raw` option to * `gdk-pixbuf-csource`. A sample invocation would be: * - * |[ - * gdk-pixbuf-csource --raw --name=myimage_inline myimage.png - * ]| + * ``` + * gdk-pixbuf-csource --raw --name=myimage_inline myimage.png + * ``` * * For the typical case where the inline pixbuf is read-only static data, * you don't need to copy the pixel data unless you intend to write to - * it, so you can pass %FALSE for @copy_pixels. (If you pass `--rle` to - * `gdk-pixbuf-csource`, a copy will be made even if @copy_pixels is %FALSE, - * so using this option is generally a bad idea.) + * it, so you can pass `FALSE` for `copy_pixels`. If you pass `--rle` to + * `gdk-pixbuf-csource`, a copy will be made even if `copy_pixels` is `FALSE`, + * so using this option is generally a bad idea. * * If you create a pixbuf from const inline data compiled into your * program, it's probably safe to ignore errors and disable length checks, * since things will always succeed: - * |[ + * + * ```c * pixbuf = gdk_pixbuf_new_from_inline (-1, myimage_inline, FALSE, NULL); - * ]| + * ``` * * For non-const inline data, you could get out of memory. For untrusted * inline data located at runtime, you could have corrupt inline data in * addition. * - * Return value: A newly-created #GdkPixbuf structure with a reference, - * count of 1, or %NULL if an error occurred. + * Return value: A newly-created pixbuf * - * Deprecated: 2.32: Use #GResource instead. + * Deprecated: 2.32: Use `GResource` instead. **/ GdkPixbuf* gdk_pixbuf_new_from_inline (gint data_length, -- cgit v1.2.1