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

[Emmanuele Bassi <ebassi src gnome org>]

commit d2cb184255008e19ac5ae4ee01c6d0ae8aa4bd6c
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Sun Mar 21 13:17:20 2021 +0000

    docs: Update pixbuf-animation style

 gdk-pixbuf/gdk-pixbuf-animation.c | 153 +++++++++++++++++++++-----------------
 1 file changed, 83 insertions(+), 70 deletions(-)
---
diff --git a/gdk-pixbuf/gdk-pixbuf-animation.c b/gdk-pixbuf/gdk-pixbuf-animation.c
index 9b7372e00..6f2c170b8 100644
--- a/gdk-pixbuf/gdk-pixbuf-animation.c
+++ b/gdk-pixbuf/gdk-pixbuf-animation.c
@@ -147,18 +147,19 @@ noop_updated_notify (GdkPixbuf *pixbuf,
 /**
  * gdk_pixbuf_animation_new_from_file:
  * @filename: (type filename): Name of file to load, in the GLib file
- *     name encoding
+ *   name encoding
  * @error: return location for error
  *
- * Creates a new animation by loading it from a file. The file format is
- * detected automatically. If the file's format does not support multi-frame
- * images, then an animation with a single frame will be created. Possible errors
- * are in the #GDK_PIXBUF_ERROR and #G_FILE_ERROR domains.
+ * Creates a new animation by loading it from a file.
  *
- * Return value: A newly-created animation with a reference count of 1, or %NULL
- * if any of several error conditions ocurred:  the file could not be opened,
- * there was no loader for the file's format, there was not enough memory to
- * allocate the image buffer, or the image file contained invalid data.
+ * The file format is detected automatically.
+ *
+ * If the file's format does not support multi-frame images, then an animation
+ * with a single frame will be created.
+ *
+ * Possible errors are in the `GDK_PIXBUF_ERROR` and `G_FILE_ERROR` domains.
+ *
+ * Return value: (transfer full) (nullable): A newly-created animation
  */
 GdkPixbufAnimation *
 gdk_pixbuf_animation_new_from_file (const gchar  *filename,
@@ -329,7 +330,7 @@ fail_begin_load:
  *
  * Same as gdk_pixbuf_animation_new_from_file()
  *
- * Return value: A newly-created animation with a reference count of 1, or %NULL
+ * Return value: A newly-created animation with a reference count of 1, or `NULL`
  * if any of several error conditions ocurred:  the file could not be opened,
  * there was no loader for the file's format, there was not enough memory to
  * allocate the image buffer, or the image file contained invalid data.
@@ -344,24 +345,24 @@ gdk_pixbuf_animation_new_from_file_utf8 (const gchar  *filename,
 
 /**
  * gdk_pixbuf_animation_new_from_stream:
- * @stream:  a #GInputStream to load the pixbuf from
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
+ * @stream:  a `GInputStream` to load the pixbuf from
+ * @cancellable: (nullable): optional `GCancellable` object
  * @error: Return location for an error
  *
  * Creates a new animation by loading it from an input stream.
  *
- * The file format is detected automatically. If %NULL is returned, then
- * @error will be set. The @cancellable can be used to abort the operation
- * from another thread. If the operation was cancelled, the error
- * %G_IO_ERROR_CANCELLED will be returned. Other possible errors are in
- * the #GDK_PIXBUF_ERROR and %G_IO_ERROR domains.
+ * The file format is detected automatically.
+ *
+ * If `NULL` is returned, then @error will be set.
+ *
+ * The @cancellable can be used to abort the operation from another thread.
+ * If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be
+ * returned. Other possible errors are in the `GDK_PIXBUF_ERROR` and
+ * `G_IO_ERROR` domains.
  *
  * The stream is not closed.
  *
- * Return value: A newly-created pixbuf, or %NULL if any of several error
- * conditions occurred: the file could not be opened, the image format is
- * not supported, there was not enough memory to allocate the image buffer,
- * the stream contained invalid data, or the operation was cancelled.
+ * Return value: (transfer full) (nullable): A newly-created animation
  *
  * Since: 2.28
  */
@@ -442,8 +443,8 @@ animation_new_from_stream_thread (GTask        *task,
 /**
  * gdk_pixbuf_animation_new_from_stream_async:
  * @stream: a #GInputStream from which to load the animation
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
- * @callback: a #GAsyncReadyCallback to call when the pixbuf is loaded
+ * @cancellable: (nullable): optional #GCancellable object
+ * @callback: a `GAsyncReadyCallback` to call when the pixbuf is loaded
  * @user_data: the data to pass to the callback function
  *
  * Creates a new animation by asynchronously loading an image from an input stream.
@@ -451,7 +452,7 @@ animation_new_from_stream_thread (GTask        *task,
  * For more details see gdk_pixbuf_new_from_stream(), which is the synchronous
  * version of this function.
  *
- * When the operation is finished, @callback will be called in the main thread.
+ * When the operation is finished, `callback` will be called in the main thread.
  * You can then call gdk_pixbuf_animation_new_from_stream_finish() to get the
  * result of the operation.
  *
@@ -478,13 +479,12 @@ gdk_pixbuf_animation_new_from_stream_async (GInputStream        *stream,
 /**
  * gdk_pixbuf_animation_new_from_stream_finish:
  * @async_result: a #GAsyncResult
- * @error: a #GError, or %NULL
+ * @error: a #GError, or `NULL`
  *
  * Finishes an asynchronous pixbuf animation creation operation started with
- * gdk_pixbuf_animation_new_from_stream_async().
+ * [func@GdkPixbuf.PixbufAnimation.new_from_stream_async].
  *
- * Return value: a #GdkPixbufAnimation or %NULL on error. Free the returned
- * object with g_object_unref().
+ * Return value: (transfer full) (nullable): the newly created animation
  *
  * Since: 2.28
  **/
@@ -508,13 +508,10 @@ gdk_pixbuf_animation_new_from_stream_finish (GAsyncResult  *async_result,
  *
  * Creates a new pixbuf animation by loading an image from an resource.
  *
- * The file format is detected automatically. If %NULL is returned, then
+ * The file format is detected automatically. If `NULL` is returned, then
  * @error will be set.
  *
- * Return value: A newly-created animation, or %NULL if any of several error
- * conditions occurred: the file could not be opened, the image format is
- * not supported, there was not enough memory to allocate the image buffer,
- * the stream contained invalid data, or the operation was cancelled.
+ * Return value: (transfer full) (nullable): A newly-created animation
  *
  * Since: 2.28
  */
@@ -576,12 +573,14 @@ gdk_pixbuf_animation_unref (GdkPixbufAnimation *animation)
  * gdk_pixbuf_animation_is_static_image:
  * @animation: a #GdkPixbufAnimation
  *
+ * Checks whether the animation is a static image.
+ *
  * If you load a file with gdk_pixbuf_animation_new_from_file() and it
  * turns out to be a plain, unanimated image, then this function will
- * return %TRUE. Use gdk_pixbuf_animation_get_static_image() to retrieve
+ * return `TRUE`. Use gdk_pixbuf_animation_get_static_image() to retrieve
  * the image.
  *
- * Return value: %TRUE if the "animation" was really just an image
+ * Return value: `TRUE` if the "animation" was really just an image
  */
 gboolean
 gdk_pixbuf_animation_is_static_image (GdkPixbufAnimation *animation)
@@ -595,12 +594,17 @@ gdk_pixbuf_animation_is_static_image (GdkPixbufAnimation *animation)
  * gdk_pixbuf_animation_get_static_image:
  * @animation: a #GdkPixbufAnimation
  *
+ * Retrieves a static image for the animation.
+ *
  * If an animation is really just a plain image (has only one frame),
- * this function returns that image. If the animation is an animation,
- * this function returns a reasonable thing to display as a static
- * unanimated image, which might be the first frame, or something more
- * sophisticated. If an animation hasn't loaded any frames yet, this
- * function will return %NULL.
+ * this function returns that image.
+ *
+ * If the animation is an animation, this function returns a reasonable
+ * image to use as a static unanimated image, which might be the first
+ * frame, or something more sophisticated depending on the file format.
+ *
+ * If an animation hasn't loaded any frames yet, this function will
+ * return `NULL`.
  *
  * Return value: (transfer none): unanimated image representing the animation
  */
@@ -662,9 +666,10 @@ gdk_pixbuf_animation_get_height (GdkPixbufAnimation *animation)
  * @animation: a #GdkPixbufAnimation
  * @start_time: (allow-none): time when the animation starts playing
  *
- * Get an iterator for displaying an animation. The iterator provides
- * the frames that should be displayed at a given time. It should be
- * freed after use with g_object_unref().
+ * Get an iterator for displaying an animation.
+ *
+ * The iterator provides the frames that should be displayed at a
+ * given time.
  *
  * @start_time would normally come from g_get_current_time(), and marks
  * the beginning of animation playback. After creating an iterator, you
@@ -676,7 +681,7 @@ gdk_pixbuf_animation_get_height (GdkPixbufAnimation *animation)
  * the image is updated, you should reinstall the timeout with the new,
  * possibly-changed delay time.
  *
- * As a shortcut, if @start_time is %NULL, the result of
+ * As a shortcut, if @start_time is `NULL`, the result of
  * g_get_current_time() will be used automatically.
  *
  * To update the image (i.e. possibly change the result of
@@ -687,14 +692,14 @@ gdk_pixbuf_animation_get_height (GdkPixbufAnimation *animation)
  * after the delay time, you should also update it whenever you
  * receive the area_updated signal and
  * gdk_pixbuf_animation_iter_on_currently_loading_frame() returns
- * %TRUE. In this case, the frame currently being fed into the loader
+ * `TRUE`. In this case, the frame currently being fed into the loader
  * has received new data, so needs to be refreshed. The delay time for
  * a frame may also be modified after an area_updated signal, for
  * example if the delay time for a frame is encoded in the data after
  * the frame itself. So your timeout should be reinstalled after any
  * area_updated signal.
  *
- * A delay time of -1 is possible, indicating "infinite."
+ * A delay time of -1 is possible, indicating "infinite".
  *
  * Return value: (transfer full): an iterator to move over the animation
  */
@@ -732,9 +737,10 @@ gdk_pixbuf_animation_iter_init (GdkPixbufAnimationIter *iter)
  * @iter: an animation iterator
  *
  * Gets the number of milliseconds the current pixbuf should be displayed,
- * or -1 if the current pixbuf should be displayed forever. g_timeout_add()
- * conveniently takes a timeout in milliseconds, so you can use a timeout
- * to schedule the next update.
+ * or -1 if the current pixbuf should be displayed forever.
+ *
+ * The `g_timeout_add()` function conveniently takes a timeout in milliseconds,
+ * so you can use a timeout to schedule the next update.
  *
  * Note that some formats, like GIF, might clamp the timeout values in the
  * image file to avoid updates that are just too quick. The minimum timeout
@@ -755,17 +761,21 @@ gdk_pixbuf_animation_iter_get_delay_time (GdkPixbufAnimationIter *iter)
  * gdk_pixbuf_animation_iter_get_pixbuf:
  * @iter: an animation iterator
  *
- * Gets the current pixbuf which should be displayed; the pixbuf might not
- * be the same size as the animation itself
+ * Gets the current pixbuf which should be displayed.
+ *
+ * The pixbuf might not be the same size as the animation itself
  * (gdk_pixbuf_animation_get_width(), gdk_pixbuf_animation_get_height()).
- * This pixbuf should be displayed for
- * gdk_pixbuf_animation_iter_get_delay_time() milliseconds. The caller
- * of this function does not own a reference to the returned pixbuf;
- * the returned pixbuf will become invalid when the iterator advances
- * to the next frame, which may happen anytime you call
- * gdk_pixbuf_animation_iter_advance(). Copy the pixbuf to keep it
- * (don't just add a reference), as it may get recycled as you advance
- * the iterator.
+ *
+ * This pixbuf should be displayed for gdk_pixbuf_animation_iter_get_delay_time()
+ * milliseconds.
+ *
+ * The caller of this function does not own a reference to the returned
+ * pixbuf; the returned pixbuf will become invalid when the iterator
+ * advances to the next frame, which may happen anytime you call
+ * gdk_pixbuf_animation_iter_advance().
+ *
+ * Copy the pixbuf to keep it (don't just add a reference), as it may get
+ * recycled as you advance the iterator.
  *
  * Return value: (transfer none): the pixbuf to be displayed
  */
@@ -783,12 +793,13 @@ gdk_pixbuf_animation_iter_get_pixbuf (GdkPixbufAnimationIter *iter)
  * @iter: a #GdkPixbufAnimationIter
  *
  * Used to determine how to respond to the area_updated signal on
- * #GdkPixbufLoader when loading an animation. area_updated is emitted
- * for an area of the frame currently streaming in to the loader. So if
- * you're on the currently loading frame, you need to redraw the screen for
- * the updated area.
+ * #GdkPixbufLoader when loading an animation.
  *
- * Return value: %TRUE if the frame we're on is partially loaded, or the last frame
+ * The `::area_updated` signal is emitted for an area of the frame currently
+ * streaming in to the loader. So if you're on the currently loading frame,
+ * you will need to redraw the screen for the updated area.
+ *
+ * Return value: `TRUE` if the frame we're on is partially loaded, or the last frame
  */
 gboolean
 gdk_pixbuf_animation_iter_on_currently_loading_frame (GdkPixbufAnimationIter *iter)
@@ -804,8 +815,10 @@ gdk_pixbuf_animation_iter_on_currently_loading_frame (GdkPixbufAnimationIter *it
  * @iter: a #GdkPixbufAnimationIter
  * @current_time: (allow-none): current time
  *
- * Possibly advances an animation to a new frame. Chooses the frame based
- * on the start time passed to gdk_pixbuf_animation_get_iter().
+ * Possibly advances an animation to a new frame.
+ *
+ * Chooses the frame based on the start time passed to
+ * gdk_pixbuf_animation_get_iter().
  *
  * @current_time would normally come from g_get_current_time(), and
  * must be greater than or equal to the time passed to
@@ -814,17 +827,17 @@ gdk_pixbuf_animation_iter_on_currently_loading_frame (GdkPixbufAnimationIter *it
  * called. That is, you can't go backward in time; animations only
  * play forward.
  *
- * As a shortcut, pass %NULL for the current time and g_get_current_time()
+ * As a shortcut, pass `NULL` for the current time and g_get_current_time()
  * will be invoked on your behalf. So you only need to explicitly pass
  * @current_time if you're doing something odd like playing the animation
  * at double speed.
  *
- * If this function returns %FALSE, there's no need to update the animation
+ * If this function returns `FALSE`, there's no need to update the animation
  * display, assuming the display had been rendered prior to advancing;
- * if %TRUE, you need to call gdk_pixbuf_animation_iter_get_pixbuf()
+ * if `TRUE`, you need to call gdk_pixbuf_animation_iter_get_pixbuf()
  * and update the display with the new pixbuf.
  *
- * Returns: %TRUE if the image may need updating
+ * Returns: `TRUE` if the image may need updating
  */
 gboolean
 gdk_pixbuf_animation_iter_advance (GdkPixbufAnimationIter *iter,