[gdk-pixbuf/ebassi/gi-docgen: 11/16] docs: Update pixdata style

[Emmanuele Bassi <ebassi src gnome org>]

commit 27f5e96604763535be0213ee218f4ca7676bc410
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Sun Mar 21 12:45:56 2021 +0000

    docs: Update pixdata style

 gdk-pixbuf/gdk-pixdata.c | 117 +++++++++++++++++++++++++----------------------
 1 file changed, 63 insertions(+), 54 deletions(-)
---
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,