From f75f9bfbbf57bde6eb32b304616349c9a50ccc2e Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sun, 21 Mar 2021 13:31:35 +0000 Subject: 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 */ -- cgit v1.2.1