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

From: Emmanuele Bassi <ebassi src gnome org>
To: commits-list gnome org
Cc:
Subject: [gdk-pixbuf/ebassi/gi-docgen: 16/16] docs: Update pixbuf-loader style
Date: Sun, 21 Mar 2021 13:32:30 +0000 (UTC)

commit f75f9bfbbf57bde6eb32b304616349c9a50ccc2e
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Sun Mar 21 13:31:35 2021 +0000

    docs: Update pixbuf-loader style

 gdk-pixbuf/gdk-pixbuf-loader.c | 168 ++++++++++++++++++++++-------------------
 1 file changed, 89 insertions(+), 79 deletions(-)
---
diff --git a/gdk-pixbuf/gdk-pixbuf-loader.c b/gdk-pixbuf/gdk-pixbuf-loader.c
index 5ef462d0d..51202b6f1 100644
--- a/gdk-pixbuf/gdk-pixbuf-loader.c
+++ b/gdk-pixbuf/gdk-pixbuf-loader.c
@@ -134,9 +134,11 @@ gdk_pixbuf_loader_class_init (GdkPixbufLoaderClass *class)
          *
          * This signal is emitted when the pixbuf loader has been fed the
          * initial amount of data that is required to figure out the size
-         * of the image that it will create.  Applications can call  
-         * gdk_pixbuf_loader_set_size() in response to this signal to set
-         * the desired size to which the image should be scaled.
+         * of the image that it will create.
+         *
+         * Applications can call gdk_pixbuf_loader_set_size() in response
+         * to this signal to set the desired size to which the image
+         * should be scaled.
          */
         pixbuf_loader_signals[SIZE_PREPARED] =
                 g_signal_new ("size-prepared",
@@ -154,9 +156,11 @@ gdk_pixbuf_loader_class_init (GdkPixbufLoaderClass *class)
          * @loader: the object which received the signal.
          *
          * This signal is emitted when the pixbuf loader has allocated the 
-         * pixbuf in the desired size.  After this signal is emitted, 
-         * applications can call gdk_pixbuf_loader_get_pixbuf() to fetch 
-         * the partially-loaded pixbuf.
+         * pixbuf in the desired size.
+         *
+         * After this signal is emitted, applications can call
+         * gdk_pixbuf_loader_get_pixbuf() to fetch the partially-loaded
+         * pixbuf.
          */
         pixbuf_loader_signals[AREA_PREPARED] =
                 g_signal_new ("area-prepared",
@@ -176,9 +180,12 @@ gdk_pixbuf_loader_class_init (GdkPixbufLoaderClass *class)
          * @height: Height of updated area.
          *
          * This signal is emitted when a significant area of the image being
-         * loaded has been updated.  Normally it means that a complete
-         * scanline has been read in, but it could be a different area as
-         * well.  Applications can use this signal to know when to repaint
+         * loaded has been updated.
+         *
+         * Normally it means that a complete scanline has been read in, but
+         * it could be a different area as well.
+         *
+         * Applications can use this signal to know when to repaint
          * areas of an image that is being loaded.
          */
         pixbuf_loader_signals[AREA_UPDATED] =
@@ -199,6 +206,7 @@ gdk_pixbuf_loader_class_init (GdkPixbufLoaderClass *class)
          * @loader: the object which received the signal.
          *
          * This signal is emitted when gdk_pixbuf_loader_close() is called.
+         *
          * It can be used by different parts of an application to receive
          * notification when an image loader is closed by the code that
          * drives it.
@@ -255,9 +263,10 @@ gdk_pixbuf_loader_finalize (GObject *object)
  * @width: The desired width of the image being loaded.
  * @height: The desired height of the image being loaded.
  *
- * Causes the image to be scaled while it is loaded. The desired
- * image size can be determined relative to the original size of
- * the image by calling gdk_pixbuf_loader_set_size() from a
+ * Causes the image to be scaled while it is loaded.
+ *
+ * The desired image size can be determined relative to the original
+ * size of the image by calling gdk_pixbuf_loader_set_size() from a
  * signal handler for the ::size-prepared signal.
  *
  * Attempts to set the desired image size  are ignored after the 
@@ -501,15 +510,10 @@ gdk_pixbuf_loader_eat_header_write (GdkPixbufLoader *loader,
  * @count: Length of the @buf buffer in bytes.
  * @error: return location for errors
  *
- * This will cause a pixbuf loader to parse the next @count bytes of
- * an image.  It will return %TRUE if the data was loaded successfully,
- * and %FALSE if an error occurred.  In the latter case, the loader
- * will be closed, and will not accept further writes. If %FALSE is
- * returned, @error will be set to an error from the #GDK_PIXBUF_ERROR
- * or #G_FILE_ERROR domains.
+ * Parses the next `count` bytes in the given image buffer.
  *
- * Return value: %TRUE if the write was successful, or %FALSE if the loader
- * cannot parse the buffer.
+ * Return value: `TRUE` if the write was successful, or
+ *   `FALSE` if the loader cannot parse the buffer
  **/
 gboolean
 gdk_pixbuf_loader_write (GdkPixbufLoader *loader,
@@ -563,20 +567,13 @@ gdk_pixbuf_loader_write (GdkPixbufLoader *loader,
 /**
  * gdk_pixbuf_loader_write_bytes:
  * @loader: A pixbuf loader.
- * @buffer: The image data as a #GBytes
+ * @buffer: The image data as a `GBytes` buffer.
  * @error: return location for errors
  *
- * This will cause a pixbuf loader to parse a buffer inside a #GBytes
- * for an image.  It will return %TRUE if the data was loaded successfully,
- * and %FALSE if an error occurred.  In the latter case, the loader
- * will be closed, and will not accept further writes. If %FALSE is
- * returned, @error will be set to an error from the #GDK_PIXBUF_ERROR
- * or #G_FILE_ERROR domains.
- *
- * See also: gdk_pixbuf_loader_write()
+ * Parses the next contents of the given image buffer.
  *
- * Return value: %TRUE if the write was successful, or %FALSE if the loader
- * cannot parse the buffer.
+ * Return value: `TRUE` if the write was successful, or `FALSE` if
+ *   the loader cannot parse the buffer
  *
  * Since: 2.30
  */
@@ -612,14 +609,16 @@ gdk_pixbuf_loader_new (void)
 /**
  * gdk_pixbuf_loader_new_with_type:
  * @image_type: name of the image format to be loaded with the image
- * @error: (allow-none): return location for an allocated #GError, or %NULL to ignore errors
+ * @error: (allow-none): return location for an allocated #GError, or `NULL` to ignore errors
  *
  * Creates a new pixbuf loader object that always attempts to parse
  * image data as if it were an image of type @image_type, instead of
- * identifying the type automatically. Useful if you want an error if
- * the image isn't the expected type, for loading image formats
- * that can't be reliably identified by looking at the data, or if
- * the user manually forces a specific type.
+ * identifying the type automatically.
+ *
+ * This function is useful if you want an error if the image isn't the
+ * expected type; for loading image formats that can't be reliably
+ * identified by looking at the data; or if the user manually forces
+ * a specific type.
  *
  * The list of supported image formats depends on what image loaders
  * are installed, but typically "png", "jpeg", "gif", "tiff" and 
@@ -655,14 +654,16 @@ gdk_pixbuf_loader_new_with_type (const char *image_type,
 /**
  * gdk_pixbuf_loader_new_with_mime_type:
  * @mime_type: the mime type to be loaded 
- * @error: (allow-none): return location for an allocated #GError, or %NULL to ignore errors
+ * @error: (allow-none): return location for an allocated #GError, or `NULL` to ignore errors
  *
  * Creates a new pixbuf loader object that always attempts to parse
- * image data as if it were an image of mime type @mime_type, instead of
- * identifying the type automatically. Useful if you want an error if
- * the image isn't the expected mime type, for loading image formats
- * that can't be reliably identified by looking at the data, or if
- * the user manually forces a specific mime type.
+ * image data as if it were an image of MIME type @mime_type, instead of
+ * identifying the type automatically.
+ *
+ * This function is useful if you want an error if the image isn't the
+ * expected MIME type; for loading image formats that can't be reliably
+ * identified by looking at the data; or if the user manually forces a
+ * specific MIME type.
  *
  * The list of supported mime types depends on what image loaders
  * are installed, but typically "image/png", "image/jpeg", "image/gif", 
@@ -672,6 +673,7 @@ gdk_pixbuf_loader_new_with_type (const char *image_type,
  * structs returned by gdk_pixbuf_get_formats().
  *
  * Return value: A newly-created pixbuf loader.
+ *
  * Since: 2.4
  **/
 GdkPixbufLoader *
@@ -737,19 +739,23 @@ _gdk_pixbuf_loader_new_with_filename (const char *filename)
  * @loader: A pixbuf loader.
  *
  * Queries the #GdkPixbuf that a pixbuf loader is currently creating.
+ *
  * In general it only makes sense to call this function after the
- * "area-prepared" signal has been emitted by the loader; this means
- * that enough data has been read to know the size of the image that
- * will be allocated.  If the loader has not received enough data via
- * gdk_pixbuf_loader_write(), then this function returns %NULL.  The
- * returned pixbuf will be the same in all future calls to the loader,
- * so simply calling g_object_ref() should be sufficient to continue
- * using it.  Additionally, if the loader is an animation, it will
- * return the "static image" of the animation
- * (see gdk_pixbuf_animation_get_static_image()).
+ * [signal@GdkPixbuf.PixbufLoader::area-prepared] signal has been
+ * emitted by the loader; this means that enough data has been read
+ * to know the size of the image that will be allocated.
+ *
+ * If the loader has not received enough data via gdk_pixbuf_loader_write(),
+ * then this function returns `NULL`.
+ *
+ * The returned pixbuf will be the same in all future calls to the loader,
+ * so if you want to keep using it, you should acquire a reference to it.
+ *
+ * Additionally, if the loader is an animation, it will return the "static
+ * image" of the animation (see gdk_pixbuf_animation_get_static_image()).
  * 
- * Return value: (transfer none): The #GdkPixbuf that the loader is creating, or %NULL if not
- * enough data has been read to determine how to create the image buffer.
+ * Return value: (transfer none) (nullable): The pixbuf that the loader is
+ *   creating
  **/
 GdkPixbuf *
 gdk_pixbuf_loader_get_pixbuf (GdkPixbufLoader *loader)
@@ -771,14 +777,17 @@ gdk_pixbuf_loader_get_pixbuf (GdkPixbufLoader *loader)
  * @loader: A pixbuf loader
  *
  * Queries the #GdkPixbufAnimation that a pixbuf loader is currently creating.
- * In general it only makes sense to call this function after the "area-prepared"
- * signal has been emitted by the loader. If the loader doesn't have enough
- * bytes yet (hasn't emitted the "area-prepared" signal) this function will 
- * return %NULL.
- *
- * Return value: (transfer none): The #GdkPixbufAnimation that the loader is loading, or %NULL if
- * not enough data has been read to determine the information.
-**/
+ *
+ * In general it only makes sense to call this function after the
+ * [signal@GdkPixbuf.PixbufLoader::area-prepared] signal has been emitted by
+ * the loader.
+ *
+ * If the loader doesn't have enough bytes yet, and hasn't emitted the `area-prepared`
+ * signal, this function will return `NULL`.
+ *
+ * Return value: (transfer none) (nullable): The animation that the loader is
+ *   currently loading
+ */
 GdkPixbufAnimation *
 gdk_pixbuf_loader_get_animation (GdkPixbufLoader *loader)
 {
@@ -794,24 +803,27 @@ gdk_pixbuf_loader_get_animation (GdkPixbufLoader *loader)
 /**
  * gdk_pixbuf_loader_close:
  * @loader: A pixbuf loader.
- * @error: (allow-none): return location for a #GError, or %NULL to ignore errors
+ * @error: (allow-none): return location for a #GError, or `NULL` to ignore errors
  *
  * Informs a pixbuf loader that no further writes with
  * gdk_pixbuf_loader_write() will occur, so that it can free its
- * internal loading structures. Also, tries to parse any data that
- * hasn't yet been parsed; if the remaining data is partial or
- * corrupt, an error will be returned.  If %FALSE is returned, @error
- * will be set to an error from the #GDK_PIXBUF_ERROR or #G_FILE_ERROR
- * domains. If you're just cancelling a load rather than expecting it
- * to be finished, passing %NULL for @error to ignore it is
- * reasonable.
- *
- * Remember that this does not unref the loader, so if you plan not to
- * use it anymore, please g_object_unref() it.
- *
- * Returns: %TRUE if all image data written so far was successfully
-            passed out via the update_area signal
- **/
+ * internal loading structures.
+ *
+ * This function also tries to parse any data that hasn't yet been parsed;
+ * if the remaining data is partial or corrupt, an error will be returned.
+ *
+ * If `FALSE` is returned, `error` will be set to an error from the
+ * `GDK_PIXBUF_ERROR` or `G_FILE_ERROR` domains.
+ *
+ * If you're just cancelling a load rather than expecting it to be finished,
+ * passing `NULL` for `error` to ignore it is reasonable.
+ *
+ * Remember that this function does not release a reference on the loader, so
+ * you will need to explicitly release any reference you hold.
+ *
+ * Returns: `TRUE` if all image data written so far was successfully
+ *   passed out via the update_area signal
+ */
 gboolean
 gdk_pixbuf_loader_close (GdkPixbufLoader *loader,
                          GError         **error)
@@ -883,9 +895,7 @@ gdk_pixbuf_loader_close (GdkPixbufLoader *loader,
  * Obtains the available information about the format of the 
  * currently loading image file.
  *
- * Returns: (nullable) (transfer none): A #GdkPixbufFormat or
- * %NULL. The return value is owned by GdkPixbuf and should not be
- * freed.
+ * Returns: (nullable) (transfer none): A #GdkPixbufFormat
  * 
  * Since: 2.2
  */
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]