From 63e3081997f40bf0464bff714e91169bef86da9a Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sat, 20 Mar 2021 23:51:03 +0000 Subject: docs: Clean up GdkPixbuf's core API Use proper summaries; remove gtk-doc'isms; document properties. --- gdk-pixbuf/gdk-pixbuf.c | 176 +++++++++++++++++++++++++++++------------------- 1 file changed, 106 insertions(+), 70 deletions(-) (limited to 'gdk-pixbuf') diff --git a/gdk-pixbuf/gdk-pixbuf.c b/gdk-pixbuf/gdk-pixbuf.c index 383fe024b..01b53f088 100644 --- a/gdk-pixbuf/gdk-pixbuf.c +++ b/gdk-pixbuf/gdk-pixbuf.c @@ -238,7 +238,8 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass) /** * GdkPixbuf:n-channels: * - * The number of samples per pixel. + * The number of samples per pixel. + * * Currently, only 3 or 4 samples per pixel are supported. */ g_object_class_install_property (object_class, @@ -250,7 +251,13 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass) G_MAXINT, 3, PIXBUF_PARAM_FLAGS)); - + /** + * GdkPixbuf:colorspace: + * + * The color space of the pixbuf. + * + * Currently, only `GDK_COLORSPACE_RGB` is supported. + */ g_object_class_install_property (object_class, PROP_COLORSPACE, g_param_spec_enum ("colorspace", @@ -259,7 +266,11 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass) GDK_TYPE_COLORSPACE, GDK_COLORSPACE_RGB, PIXBUF_PARAM_FLAGS)); - + /** + * GdkPixbuf:has-alpha: + * + * Whether the pixbuf has an alpha channel. + */ g_object_class_install_property (object_class, PROP_HAS_ALPHA, g_param_spec_boolean ("has-alpha", @@ -267,11 +278,11 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass) _("Whether the pixbuf has an alpha channel"), FALSE, PIXBUF_PARAM_FLAGS)); - /** * GdkPixbuf:bits-per-sample: * * The number of bits per sample. + * * Currently only 8 bit per sample are supported. */ g_object_class_install_property (object_class, @@ -283,7 +294,11 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass) 16, 8, PIXBUF_PARAM_FLAGS)); - + /** + * GdkPixbuf:width: + * + * The number of columns of the pixbuf. + */ g_object_class_install_property (object_class, PROP_WIDTH, g_param_spec_int ("width", @@ -293,7 +308,11 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass) G_MAXINT, 1, PIXBUF_PARAM_FLAGS)); - + /** + * GdkPixbuf:height: + * + * The number of rows of the pixbuf. + */ g_object_class_install_property (object_class, PROP_HEIGHT, g_param_spec_int ("height", @@ -303,13 +322,14 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass) G_MAXINT, 1, PIXBUF_PARAM_FLAGS)); - /** * GdkPixbuf:rowstride: * * The number of bytes between the start of a row and - * the start of the next row. This number must (obviously) - * be at least as large as the width of the pixbuf. + * the start of the next row. + * + * This number must (obviously) be at least as large as the + * width of the pixbuf. */ g_object_class_install_property (object_class, PROP_ROWSTRIDE, @@ -320,18 +340,22 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass) G_MAXINT, 1, PIXBUF_PARAM_FLAGS)); - + /** + * GdkPixbuf:pixels: + * + * A pointer to the pixel data of the pixbuf. + */ g_object_class_install_property (object_class, PROP_PIXELS, g_param_spec_pointer ("pixels", _("Pixels"), _("A pointer to the pixel data of the pixbuf"), PIXBUF_PARAM_FLAGS)); - /** * GdkPixbuf::pixel-bytes: * * If set, this pixbuf was created from read-only #GBytes. + * * Replaces GdkPixbuf::pixels. * * Since: 2.32 @@ -539,8 +563,10 @@ free_buffer (guchar *pixels, gpointer data) * @height: Height of image in pixels, must be > 0 * * Calculates the rowstride that an image created with those values would - * have. This is useful for front-ends and backends that want to sanity - * check image values without needing to create them. + * have. + * + * This function is useful for front-ends and backends that want to check + * image values without needing to create a `GdkPixbuf`. * * Return value: the rowstride for the given values, or -1 in case of error. * @@ -578,12 +604,14 @@ gdk_pixbuf_calculate_rowstride (GdkColorspace colorspace, * @width: Width of image in pixels, must be > 0 * @height: Height of image in pixels, must be > 0 * - * Creates a new #GdkPixbuf structure and allocates a buffer for it. The - * buffer has an optimal rowstride. Note that the buffer is not cleared; + * Creates a new `GdkPixbuf` structure and allocates a buffer for it. + * + * If the allocation of the buffer failed, this function will return `NULL`. + * + * The buffer has an optimal rowstride. Note that the buffer is not cleared; * you will have to fill it completely yourself. * - * Return value: (nullable): A newly-created #GdkPixbuf with a reference count of 1, or - * %NULL if not enough memory could be allocated for the image buffer. + * Return value: (transfer full) (nullable): A newly-created pixel buffer **/ GdkPixbuf * gdk_pixbuf_new (GdkColorspace colorspace, @@ -616,12 +644,13 @@ gdk_pixbuf_new (GdkColorspace colorspace, * gdk_pixbuf_copy: * @pixbuf: A pixbuf. * - * Creates a new #GdkPixbuf with a copy of the information in the specified - * @pixbuf. Note that this does not copy the options set on the original #GdkPixbuf, + * Creates a new `GdkPixbuf` with a copy of the information in the specified + * `pixbuf`. + * + * Note that this does not copy the options set on the original `GdkPixbuf`, * use gdk_pixbuf_copy_options() for this. * - * Return value: (nullable) (transfer full): A newly-created pixbuf with a reference count of 1, or %NULL if - * not enough memory could be allocated. + * Return value: (nullable) (transfer full): A newly-created pixbuf **/ GdkPixbuf * gdk_pixbuf_copy (const GdkPixbuf *pixbuf) @@ -655,19 +684,20 @@ gdk_pixbuf_copy (const GdkPixbuf *pixbuf) /** * gdk_pixbuf_new_subpixbuf: - * @src_pixbuf: a #GdkPixbuf + * @src_pixbuf: a `GdkPixbuf` * @src_x: X coord in @src_pixbuf * @src_y: Y coord in @src_pixbuf * @width: width of region in @src_pixbuf * @height: height of region in @src_pixbuf * - * Creates a new pixbuf which represents a sub-region of @src_pixbuf. + * Creates a new pixbuf which represents a sub-region of `src_pixbuf`. + * * The new pixbuf shares its pixels with the original pixbuf, so * writing to one affects both. The new pixbuf holds a reference to - * @src_pixbuf, so @src_pixbuf will not be finalized until the new + * `src_pixbuf`, so `src_pixbuf` will not be finalized until the new * pixbuf is finalized. * - * Note that if @src_pixbuf is read-only, this function will force it + * Note that if `src_pixbuf` is read-only, this function will force it * to be mutable. * * Return value: (transfer full): a new pixbuf @@ -752,7 +782,7 @@ gdk_pixbuf_get_n_channels (const GdkPixbuf *pixbuf) * * Queries whether a pixbuf has an alpha channel (opacity information). * - * Return value: %TRUE if it has an alpha channel, %FALSE otherwise. + * Return value: `TRUE` if it has an alpha channel, `FALSE` otherwise. **/ gboolean gdk_pixbuf_get_has_alpha (const GdkPixbuf *pixbuf) @@ -784,12 +814,13 @@ gdk_pixbuf_get_bits_per_sample (const GdkPixbuf *pixbuf) * * Queries a pointer to the pixel data of a pixbuf. * - * Return value: (array): A pointer to the pixbuf's pixel data. - * Please see the section on [image data][image-data] for information - * about how the pixel data is stored in memory. - * * This function will cause an implicit copy of the pixbuf data if the * pixbuf was created from read-only data. + * + * Please see the section on [image data](#image-data) for information + * about how the pixel data is stored in memory. + * + * Return value: (array): A pointer to the pixbuf's pixel data. **/ guchar * gdk_pixbuf_get_pixels (const GdkPixbuf *pixbuf) @@ -830,13 +861,15 @@ downgrade_to_pixels (const GdkPixbuf *pixbuf) * * Queries a pointer to the pixel data of a pixbuf. * - * Return value: (array length=length): A pointer to the pixbuf's - * pixel data. Please see the section on [image data][image-data] - * for information about how the pixel data is stored in memory. - * * This function will cause an implicit copy of the pixbuf data if the * pixbuf was created from read-only data. * + * Please see the section on [image data](#image-data) for information + * about how the pixel data is stored in memory. + * + * Return value: (array length=length): A pointer to the pixbuf's + * pixel data. + * * Since: 2.26 */ guchar * @@ -858,10 +891,10 @@ gdk_pixbuf_get_pixels_with_length (const GdkPixbuf *pixbuf, * gdk_pixbuf_read_pixels: * @pixbuf: A pixbuf * - * Provides a read-only pointer to the raw pixel data; must not be - * modified. This function allows skipping the implicit copy that - * must be made if gdk_pixbuf_get_pixels() is called on a read-only - * pixbuf. + * Provides a read-only pointer to the raw pixel data. + * + * This function allows skipping the implicit copy that must be made + * if gdk_pixbuf_get_pixels() is called on a read-only pixbuf. * * Returns: a read-only pointer to the raw pixel data * @@ -893,9 +926,10 @@ gdk_pixbuf_read_pixels (const GdkPixbuf *pixbuf) * @pixbuf: A pixbuf * * Provides a #GBytes buffer containing the raw pixel data; the data - * must not be modified. This function allows skipping the implicit - * copy that must be made if gdk_pixbuf_get_pixels() is called on a - * read-only pixbuf. + * must not be modified. + * + * This function allows skipping the implicit copy that must be made + * if gdk_pixbuf_get_pixels() is called on a read-only pixbuf. * * Returns: (transfer full): A new reference to a read-only copy of * the pixel data. Note that for mutable pixbufs, this function will @@ -1008,15 +1042,16 @@ gdk_pixbuf_error_quark (void) /** * gdk_pixbuf_fill: - * @pixbuf: a #GdkPixbuf - * @pixel: RGBA pixel to clear to - * (0xffffffff is opaque white, 0x00000000 transparent black) + * @pixbuf: a `GdkPixbuf` + * @pixel: RGBA pixel to used to clear (`0xffffffff` is opaque white, + * `0x00000000` transparent black) * * Clears a pixbuf to the given RGBA value, converting the RGBA value into - * the pixbuf's pixel format. The alpha will be ignored if the pixbuf - * doesn't have an alpha channel. - * - **/ + * the pixbuf's pixel format. + * + * The alpha component will be ignored if the pixbuf doesn't have an alpha + * channel. + */ void gdk_pixbuf_fill (GdkPixbuf *pixbuf, guint32 pixel) @@ -1075,7 +1110,7 @@ gdk_pixbuf_fill (GdkPixbuf *pixbuf, /** * gdk_pixbuf_get_option: - * @pixbuf: a #GdkPixbuf + * @pixbuf: a `GdkPixbuf` * @key: a nul-terminated string. * * Looks up @key in the list of options that may have been attached to the @@ -1094,8 +1129,7 @@ gdk_pixbuf_fill (GdkPixbuf *pixbuf, * Since 2.36.6, the JPEG loader sets the "comment" option with the comment * EXIF tag. * - * Return value: the value associated with @key. This is a nul-terminated - * string that should not be freed or %NULL if @key was not found. + * Return value: (transfer none) (nullable): the value associated with `key` **/ const gchar * gdk_pixbuf_get_option (GdkPixbuf *pixbuf, @@ -1121,15 +1155,14 @@ gdk_pixbuf_get_option (GdkPixbuf *pixbuf, /** * gdk_pixbuf_get_options: - * @pixbuf: a #GdkPixbuf + * @pixbuf: a `GdkPixbuf` * - * Returns a #GHashTable with a list of all the options that may have been - * attached to the @pixbuf when it was loaded, or that may have been - * attached by another function using gdk_pixbuf_set_option(). + * Returns a `GHashTable` with a list of all the options that may have been + * attached to the `pixbuf` when it was loaded, or that may have been + * attached by another function using [method@GdkPixbuf.Pixbuf.set_option]. * - * See gdk_pixbuf_get_option() for more details. - * - * Return value: (transfer container) (element-type utf8 utf8): a #GHashTable of key/values + * Return value: (transfer container) (element-type utf8 utf8): a #GHashTable + * of key/values pairs * * Since: 2.32 **/ @@ -1157,12 +1190,12 @@ gdk_pixbuf_get_options (GdkPixbuf *pixbuf) /** * gdk_pixbuf_remove_option: - * @pixbuf: a #GdkPixbuf + * @pixbuf: a `GdkPixbuf` * @key: a nul-terminated string representing the key to remove. * - * Remove the key/value pair option attached to a #GdkPixbuf. + * Removes the key/value pair option attached to a `GdkPixbuf`. * - * Return value: %TRUE if an option was removed, %FALSE if not. + * Return value: `TRUE` if an option was removed, `FALSE` if not. * * Since: 2.36 **/ @@ -1223,15 +1256,16 @@ gdk_pixbuf_remove_option (GdkPixbuf *pixbuf, /** * gdk_pixbuf_set_option: - * @pixbuf: a #GdkPixbuf + * @pixbuf: a `GdkPixbuf` * @key: a nul-terminated string. * @value: a nul-terminated string. * - * Attaches a key/value pair as an option to a #GdkPixbuf. If @key already - * exists in the list of options attached to @pixbuf, the new value is - * ignored and %FALSE is returned. + * Attaches a key/value pair as an option to a `GdkPixbuf`. + * + * If `key` already exists in the list of options attached to the `pixbuf`, + * the new value is ignored and `FALSE` is returned. * - * Return value: %TRUE on success. + * Return value: `TRUE` on success * * Since: 2.2 **/ @@ -1276,15 +1310,17 @@ gdk_pixbuf_set_option (GdkPixbuf *pixbuf, /** * gdk_pixbuf_copy_options: - * @src_pixbuf: a #GdkPixbuf to copy options from - * @dest_pixbuf: the #GdkPixbuf to copy options to + * @src_pixbuf: the source pixbuf + * @dest_pixbuf: the destination pixbuf + * + * Copies the key/value pair options attached to a `GdkPixbuf` to another + * `GdkPixbuf`. * - * Copy the key/value pair options attached to a #GdkPixbuf to another. * This is useful to keep original metadata after having manipulated * a file. However be careful to remove metadata which you've already * applied, such as the "orientation" option after rotating the image. * - * Return value: %TRUE on success. + * Return value: `TRUE` on success. * * Since: 2.36 **/ -- cgit v1.2.1