From 5f92ced1f3dcc1362d99e28d0b9ed234fa7c47c2 Mon Sep 17 00:00:00 2001 From: Niels De Graef Date: Sat, 3 Aug 2019 00:36:59 +0200 Subject: [PATCH] Add (nullable) if applicable Basically this commit makes sure that all return values that are marked as "Returns:" also have a `(nullable)` annotation if it is mentioned on the same line that NULL can also be returned. This will prevent a few problems in GObject-introspection. --- app/config/gimprc.c | 2 +- app/core/gimpcontainer.c | 8 ++++---- app/core/gimpdata.c | 3 ++- app/core/gimpidtable.c | 3 ++- app/core/gimptag.c | 8 ++++---- app/core/gimpviewable.c | 12 ++++++------ app/display/gimpimagewindow.c | 2 +- app/text/gimptextlayer.c | 2 +- app/widgets/gimpclipboard.c | 10 +++++----- libgimp/gimpimage.c | 4 ++-- libgimp/gimpplugin.c | 2 +- libgimp/gimpprocbrowserdialog.c | 2 +- libgimp/gimpui.c | 2 +- libgimpcolor/gimpcolorprofile.c | 12 ++++++------ libgimpcolor/gimpcolortransform.c | 4 ++-- libgimpcolor/gimppixbuf.c | 4 ++-- libgimpconfig/gimpconfig-path.c | 3 ++- libgimpconfig/gimpconfigwriter.c | 10 +++++----- libgimpthumb/gimpthumbnail.c | 2 +- libgimpwidgets/gimpnumberpairentry.c | 4 ++-- libgimpwidgets/gimppageselector.c | 12 ++++++------ libgimpwidgets/gimpwidgetsutils.c | 6 ++++-- plug-ins/file-jpeg/jpeg-settings.c | 2 +- 23 files changed, 62 insertions(+), 57 deletions(-) diff --git a/app/config/gimprc.c b/app/config/gimprc.c index 513ab467b4..2b9e648b4d 100644 --- a/app/config/gimprc.c +++ b/app/config/gimprc.c @@ -382,7 +382,7 @@ gimp_rc_set_autosave (GimpRc *rc, * is returned. If no property is found, the list of unknown tokens * attached to the @rc object is searched. * - * Returns: a newly allocated string representing the value or %NULL + * Returns: (nullable): a newly allocated string representing the value or %NULL * if the key couldn't be found. **/ gchar * diff --git a/app/core/gimpcontainer.c b/app/core/gimpcontainer.c index 8540e49da8..41497ac4db 100644 --- a/app/core/gimpcontainer.c +++ b/app/core/gimpcontainer.c @@ -850,8 +850,8 @@ gimp_container_get_child_by_index (GimpContainer *container, * gimp_container_get_first_child: * @container: a #GimpContainer * - * Returns: the first child object stored in @container or %NULL if the - * container is empty + * Returns: (nullable) (transfer none): the first child object stored in + * @container or %NULL if the container is empty. */ GimpObject * gimp_container_get_first_child (GimpContainer *container) @@ -869,8 +869,8 @@ gimp_container_get_first_child (GimpContainer *container) * gimp_container_get_last_child: * @container: a #GimpContainer * - * Returns: the last child object stored in @container or %NULL if the - * container is empty + * Returns: (nullable) (transfer none): the last child object stored in + * @container or %NULL if the container is empty */ GimpObject * gimp_container_get_last_child (GimpContainer *container) diff --git a/app/core/gimpdata.c b/app/core/gimpdata.c index 63421b85dd..8bbe2f5ae0 100644 --- a/app/core/gimpdata.c +++ b/app/core/gimpdata.c @@ -1134,7 +1134,8 @@ gimp_data_is_duplicatable (GimpData *data) * copied: the newly created object is not automatically given an * object name, file name, preview, etc. * - * Returns: the newly created copy, or %NULL if @data cannot be copied. + * Returns: (nullable) (transfer full): the newly created copy, or %NULL if + * @data cannot be copied. **/ GimpData * gimp_data_duplicate (GimpData *data) diff --git a/app/core/gimpidtable.c b/app/core/gimpidtable.c index b69a13d053..2307ad50cf 100644 --- a/app/core/gimpidtable.c +++ b/app/core/gimpidtable.c @@ -195,7 +195,8 @@ gimp_id_table_replace (GimpIdTable *id_table, gint id, gpointer data) * * Lookup data based on ID. * - * Returns: The data, or NULL if no data with the given ID was found. + * Returns: (nullable) (transfer none): The data, + * or %NULL if no data with the given ID was found. **/ gpointer gimp_id_table_lookup (GimpIdTable *id_table, gint id) diff --git a/app/core/gimptag.c b/app/core/gimptag.c index e3eb6328aa..0b1012a3c0 100644 --- a/app/core/gimptag.c +++ b/app/core/gimptag.c @@ -55,8 +55,8 @@ gimp_tag_init (GimpTag *tag) * * If given tag name is not valid, an attempt will be made to fix it. * - * Returns: a new #GimpTag object, or NULL if tag string is invalid and - * cannot be fixed. + * Returns: (nullable) (transfer full): a new #GimpTag object, + * or NULL if tag string is invalid and cannot be fixed. **/ GimpTag * gimp_tag_new (const char *tag_string) @@ -95,8 +95,8 @@ gimp_tag_new (const char *tag_string) * unneeded comparisons. If tag is created, however, it does not mean that * it would necessarily match with some other tag. * - * Returns: new #GimpTag object, or NULL if tag will not match with any - * other #GimpTag. + * Returns: (nullable) (transfer full): new #GimpTag object, + * or NULL if tag will not match with any other #GimpTag. **/ GimpTag * gimp_tag_try_new (const char *tag_string) diff --git a/app/core/gimpviewable.c b/app/core/gimpviewable.c index 5c6e3f4a7d..02a1f6ffac 100644 --- a/app/core/gimpviewable.c +++ b/app/core/gimpviewable.c @@ -849,7 +849,7 @@ gimp_viewable_get_popup_size (GimpViewable *viewable, * method, and executes it, caching the result. If everything fails, * %NULL is returned. * - * Returns: A #GimpTempBuf containing the preview image, or %NULL if + * Returns: (nullable): A #GimpTempBuf containing the preview image, or %NULL if * none can be found or created. **/ GimpTempBuf * @@ -912,7 +912,7 @@ gimp_viewable_get_preview (GimpViewable *viewable, * then if that fails for a "get_preview" method. This function does * not look for a cached preview. * - * Returns: A #GimpTempBuf containing the preview image, or %NULL if + * Returns: (nullable): A #GimpTempBuf containing the preview image, or %NULL if * none can be found or created. **/ GimpTempBuf * @@ -1006,8 +1006,8 @@ gimp_viewable_get_dummy_preview (GimpViewable *viewable, * method, and executes it, caching the result. If everything fails, * %NULL is returned. * - * Returns: A #GdkPixbuf containing the preview pixbuf, or %NULL if none can - * be found or created. + * Returns: (nullable): A #GdkPixbuf containing the preview pixbuf, + * or %NULL if none can be found or created. **/ GdkPixbuf * gimp_viewable_get_pixbuf (GimpViewable *viewable, @@ -1069,8 +1069,8 @@ gimp_viewable_get_pixbuf (GimpViewable *viewable, * then if that fails for a "get_pixbuf" method. This function does * not look for a cached pixbuf. * - * Returns: A #GdkPixbuf containing the preview, or %NULL if none can - * be created. + * Returns: (nullable): A #GdkPixbuf containing the preview, + * or %NULL if none can be created. **/ GdkPixbuf * gimp_viewable_get_new_pixbuf (GimpViewable *viewable, diff --git a/app/display/gimpimagewindow.c b/app/display/gimpimagewindow.c index d20b0f8d63..dfaa432fce 100644 --- a/app/display/gimpimagewindow.c +++ b/app/display/gimpimagewindow.c @@ -1593,7 +1593,7 @@ gimp_image_window_get_first_dockbook (GimpDockColumns *columns) * Gets the default dockbook, which is the dockbook in which new * dockables should be put in single-window mode. * - * Returns: The default dockbook for new dockables, or NULL if no + * Returns: (nullable): The default dockbook for new dockables, or %NULL if no * dockbook were available. **/ GtkWidget * diff --git a/app/text/gimptextlayer.c b/app/text/gimptextlayer.c index 0f35332438..002cec1904 100644 --- a/app/text/gimptextlayer.c +++ b/app/text/gimptextlayer.c @@ -429,7 +429,7 @@ gimp_text_layer_convert_type (GimpLayer *layer, * * Creates a new text layer. * - * Returns: a new #GimpTextLayer or %NULL in case of a problem + * Returns: (nullable): a new #GimpTextLayer or %NULL in case of a problem **/ GimpLayer * gimp_text_layer_new (GimpImage *image, diff --git a/app/widgets/gimpclipboard.c b/app/widgets/gimpclipboard.c index 1b599f0bb7..3919de316f 100644 --- a/app/widgets/gimpclipboard.c +++ b/app/widgets/gimpclipboard.c @@ -296,7 +296,7 @@ gimp_clipboard_has_curve (Gimp *gimp) * The returned #GimpObject needs to be unref'ed when it's no longer * needed. * - * Returns: a reference to a #GimpObject or %NULL if there's no + * Returns: (nullable): a reference to a #GimpObject or %NULL if there's no * image or buffer in the clipboard **/ GimpObject * @@ -323,7 +323,7 @@ gimp_clipboard_get_object (Gimp *gimp) * The returned #GimpImage needs to be unref'ed when it's no longer * needed. * - * Returns: a reference to a #GimpImage or %NULL if there's no + * Returns: (nullable): a reference to a #GimpImage or %NULL if there's no * image in the clipboard **/ GimpImage * @@ -382,7 +382,7 @@ gimp_clipboard_get_image (Gimp *gimp) * The returned #GimpBuffer needs to be unref'ed when it's no longer * needed. * - * Returns: a reference to a #GimpBuffer or %NULL if there's no + * Returns: (nullable): a reference to a #GimpBuffer or %NULL if there's no * image data **/ GimpBuffer * @@ -448,7 +448,7 @@ gimp_clipboard_get_buffer (Gimp *gimp) * * The returned data needs to be freed when it's no longer needed. * - * Returns: a reference to a #GimpBuffer or %NULL if there's no + * Returns: (nullable): a reference to a #GimpBuffer or %NULL if there's no * image data **/ gchar * @@ -518,7 +518,7 @@ gimp_clipboard_get_svg (Gimp *gimp, * * The returned curve needs to be unref'ed when it's no longer needed. * - * Returns: a reference to a #GimpCurve or %NULL if there's no + * Returns: (nullable): a reference to a #GimpCurve or %NULL if there's no * curve data **/ GimpCurve * diff --git a/libgimp/gimpimage.c b/libgimp/gimpimage.c index a60b74d650..762367e45c 100644 --- a/libgimp/gimpimage.c +++ b/libgimp/gimpimage.c @@ -108,8 +108,8 @@ gimp_image_get_thumbnail_data (gint32 image_ID, * * Returns exif/iptc/xmp metadata from the image. * - * Returns: (transfer full): The exif/ptc/xmp metadata, or %NULL if - * there is none. + * Returns: (nullable) (transfer full): The exif/ptc/xmp metadata, + * or %NULL if there is none. * * Since: 2.10 **/ diff --git a/libgimp/gimpplugin.c b/libgimp/gimpplugin.c index fac4b66e98..55adaad0fa 100644 --- a/libgimp/gimpplugin.c +++ b/libgimp/gimpplugin.c @@ -341,7 +341,7 @@ gimp_plug_in_get_temp_procedures (GimpPlugIn *plug_in) * This function retrieves a temporary procedure from @plug_in by the * procedure's @name. * - * Returns: (transfer none): The procedure if registered, or %NULL. + * Returns: (nullable) (transfer none): The procedure if registered, or %NULL. * * Since: 3.0 **/ diff --git a/libgimp/gimpprocbrowserdialog.c b/libgimp/gimpprocbrowserdialog.c index 1c19acd895..d804cb0871 100644 --- a/libgimp/gimpprocbrowserdialog.c +++ b/libgimp/gimpprocbrowserdialog.c @@ -284,7 +284,7 @@ gimp_proc_browser_dialog_new (const gchar *title, * * Retrieves the name of the currently selected procedure. * - * Returns: The name of the selected procedure of %NULL if no + * Returns: (nullable): The name of the selected procedure of %NULL if no * procedure is selected. * * Since: 2.4 diff --git a/libgimp/gimpui.c b/libgimp/gimpui.c index 66d227f422..64fcd475c1 100644 --- a/libgimp/gimpui.c +++ b/libgimp/gimpui.c @@ -204,7 +204,7 @@ gimp_ui_get_foreign_window (guint32 window) * You shouldn't have to call this function directly. Use * gimp_window_set_transient_for_display() instead. * - * Returns: (transfer full): A reference to a #GdkWindow or %NULL. + * Returns: (nullable) (transfer full): A reference to a #GdkWindow or %NULL. * You should unref the window using g_object_unref() as * soon as you don't need it any longer. * diff --git a/libgimpcolor/gimpcolorprofile.c b/libgimpcolor/gimpcolorprofile.c index 1c8f9a8d8d..7f7d092410 100644 --- a/libgimpcolor/gimpcolorprofile.c +++ b/libgimpcolor/gimpcolorprofile.c @@ -167,7 +167,7 @@ gimp_color_profile_finalize (GObject *object) * * This function opens an ICC color profile from @file. * - * Returns: the #GimpColorProfile, or %NULL. On error, %NULL is + * Returns: (nullable): the #GimpColorProfile, or %NULL. On error, %NULL is * returned and @error is set. * * Since: 2.10 @@ -272,7 +272,7 @@ gimp_color_profile_new_from_file (GFile *file, * This function opens an ICC color profile from memory. On error, * %NULL is returned and @error is set. * - * Returns: the #GimpColorProfile, or %NULL. + * Returns: (nullable): the #GimpColorProfile, or %NULL. * * Since: 2.10 **/ @@ -317,7 +317,7 @@ gimp_color_profile_new_from_icc_profile (const guint8 *data, * @lcms_profile pointer is not retained by the created * #GimpColorProfile. * - * Returns: the #GimpColorProfile, or %NULL. + * Returns: (nullable): the #GimpColorProfile, or %NULL. * * Since: 2.10 **/ @@ -1010,7 +1010,7 @@ gimp_color_profile_new_from_color_profile (GimpColorProfile *profile, * This function creates a new RGB #GimpColorProfile with a sRGB gamma * TRC and @profile's RGB chromacities and whitepoint. * - * Returns: (transfer full): the new #GimpColorProfile, or %NULL if + * Returns: (nullable) (transfer full): the new #GimpColorProfile, or %NULL if * @profile is not an RGB profile or not matrix-based. * * Since: 2.10 @@ -1030,7 +1030,7 @@ gimp_color_profile_new_srgb_trc_from_color_profile (GimpColorProfile *profile) * This function creates a new RGB #GimpColorProfile with a linear TRC * and @profile's RGB chromacities and whitepoint. * - * Returns: (transfer full): the new #GimpColorProfile, or %NULL if + * Returns: (nullable) (transfer full): the new #GimpColorProfile, or %NULL if * @profile is not an RGB profile or not matrix-based. * * Since: 2.10 @@ -1578,7 +1578,7 @@ gimp_color_profile_get_format (GimpColorProfile *profile, * Note that this function currently only supports RGB, RGBA, R'G'B', * R'G'B'A, Y, YA, Y', Y'A and the cairo-RGB24 and cairo-ARGB32 formats. * - * Returns: the #Babl format to be used instead of @format, or %NULL + * Returns: (nullable): the #Babl format to be used instead of @format, or %NULL * if the passed @format is not supported at all. * * Since: 2.10 diff --git a/libgimpcolor/gimpcolortransform.c b/libgimpcolor/gimpcolortransform.c index f3817ea3cd..867246c68f 100644 --- a/libgimpcolor/gimpcolortransform.c +++ b/libgimpcolor/gimpcolortransform.c @@ -176,7 +176,7 @@ gimp_color_transform_finalize (GObject *object) * returns a non-%NULL transform and the code takes care of doing only * exactly the requested color transform. * - * Returns: the #GimpColorTransform, or %NULL if there was an error. + * Returns: (nullable): the #GimpColorTransform, or %NULL if there was an error. * * Since: 2.10 **/ @@ -306,7 +306,7 @@ gimp_color_transform_new (GimpColorProfile *src_profile, * See gimp_color_transform_new() about the color spaces to transform * between. * - * Returns: the #GimpColorTransform, or %NULL if there was an error. + * Returns: (nullable): the #GimpColorTransform, or %NULL if there was an error. * * Since: 2.10 **/ diff --git a/libgimpcolor/gimppixbuf.c b/libgimpcolor/gimppixbuf.c index a0738f8b47..d2c3ae3dc7 100644 --- a/libgimpcolor/gimppixbuf.c +++ b/libgimpcolor/gimppixbuf.c @@ -123,8 +123,8 @@ gimp_pixbuf_create_buffer (GdkPixbuf *pixbuf) * Returns the ICC profile attached to the @pixbuf, or %NULL if there * is none. * - * Returns: The ICC profile data, or %NULL. The value should be freed - * with g_free(). + * Returns: (nullable): The ICC profile data, or %NULL. + * The value should be freed with g_free(). * * Since: 2.10 **/ diff --git a/libgimpconfig/gimpconfig-path.c b/libgimpconfig/gimpconfig-path.c index 0e83fa3d2b..86c258de1d 100644 --- a/libgimpconfig/gimpconfig-path.c +++ b/libgimpconfig/gimpconfig-path.c @@ -442,7 +442,8 @@ gimp_config_path_unexpand (const gchar *path, * * To reverse the expansion, use gimp_file_get_config_path(). * - * Returns: (transfer full): a newly allocated #GFile, or %NULL if the expansion failed. + * Returns: (nullable) (transfer full): a newly allocated #GFile, + * or %NULL if the expansion failed. * * Since: 2.10 **/ diff --git a/libgimpconfig/gimpconfigwriter.c b/libgimpconfig/gimpconfigwriter.c index f33096752f..47b10b8fad 100644 --- a/libgimpconfig/gimpconfigwriter.c +++ b/libgimpconfig/gimpconfigwriter.c @@ -121,7 +121,7 @@ gimp_config_writer_newline (GimpConfigWriter *writer) * possible race conditions. The temporary file is then moved to * @filename when the writer is closed. * - * Returns: a new #GimpConfigWriter or %NULL in case of an error + * Returns: (nullable): a new #GimpConfigWriter or %NULL in case of an error * * Since: 2.4 **/ @@ -158,7 +158,7 @@ gimp_config_writer_new_file (const gchar *filename, * possible race conditions. The temporary file is then moved to @file * when the writer is closed. * - * Returns: a new #GimpConfigWriter or %NULL in case of an error + * Returns: (nullable): a new #GimpConfigWriter or %NULL in case of an error * * Since: 2.10 **/ @@ -234,7 +234,7 @@ gimp_config_writer_new_gfile (GFile *file, * Creates a new #GimpConfigWriter and sets it up to write to * @output. * - * Returns: a new #GimpConfigWriter or %NULL in case of an error + * Returns: (nullable): a new #GimpConfigWriter or %NULL in case of an error * * Since: 2.10 **/ @@ -266,7 +266,7 @@ gimp_config_writer_new_stream (GOutputStream *output, * gimp_config_writer_new_fd: * @fd: * - * Returns: a new #GimpConfigWriter or %NULL in case of an error + * Returns: (nullable): a new #GimpConfigWriter or %NULL in case of an error * * Since: 2.4 **/ @@ -294,7 +294,7 @@ gimp_config_writer_new_fd (gint fd) * gimp_config_writer_new_string: * @string: * - * Returns: a new #GimpConfigWriter or %NULL in case of an error + * Returns: (nullable): a new #GimpConfigWriter or %NULL in case of an error * * Since: 2.4 **/ diff --git a/libgimpthumb/gimpthumbnail.c b/libgimpthumb/gimpthumbnail.c index 26698aaaa7..2f77cb0869 100644 --- a/libgimpthumb/gimpthumbnail.c +++ b/libgimpthumb/gimpthumbnail.c @@ -969,7 +969,7 @@ gimp_thumbnail_debug_notify (GObject *object, * In order to verify if the preview is uptodate, you should check the * "thumb_state" property after calling this function. * - * Returns: (transfer full): a preview pixbuf or %NULL if no + * Returns: (nullable) (transfer full): a preview pixbuf or %NULL if no * thumbnail was found **/ GdkPixbuf * diff --git a/libgimpwidgets/gimpnumberpairentry.c b/libgimpwidgets/gimpnumberpairentry.c index fe86823134..dc5fc99b4e 100644 --- a/libgimpwidgets/gimpnumberpairentry.c +++ b/libgimpwidgets/gimpnumberpairentry.c @@ -650,8 +650,8 @@ gimp_number_pair_entry_set_default_text (GimpNumberPairEntry *entry, * gimp_number_pair_entry_get_default_text: * @entry: A #GimpNumberPairEntry widget. * - * Returns: the string manually set to be shown, or %NULL if values are - * shown in a normal fashion. + * Returns: (nullable): the string manually set to be shown, + * or %NULL if values are shown in a normal fashion. * * Since: 2.4 */ diff --git a/libgimpwidgets/gimppageselector.c b/libgimpwidgets/gimppageselector.c index fd40635845..c7f5c3064c 100644 --- a/libgimpwidgets/gimppageselector.c +++ b/libgimpwidgets/gimppageselector.c @@ -597,9 +597,9 @@ gimp_page_selector_set_page_thumbnail (GimpPageSelector *selector, * @selector: Pointer to a #GimpPageSelector. * @page_no: The number of the page to get the thumbnail for. * - * Returns: (transfer none): The page's thumbnail, or %NULL if none is set. The returned - * pixbuf is owned by #GimpPageSelector and must not be - * unref'ed when no longer needed. + * Returns: (nullable) (transfer none): The page's thumbnail, or %NULL if none + * is set. The returned pixbuf is owned by #GimpPageSelector and must + * not be unref'ed when no longer needed. * * Since: 2.4 **/ @@ -678,9 +678,9 @@ gimp_page_selector_set_page_label (GimpPageSelector *selector, * @selector: Pointer to a #GimpPageSelector. * @page_no: The number of the page to get the thumbnail for. * - * Returns: The page's label, or %NULL if none is set. This is a newly - * allocated string that should be g_free()'d when no longer - * needed. + * Returns: (nullable) (transfer full): The page's label, or %NULL if none is + * set. This is a newly allocated string that should be g_free()'d + * when no longer needed. * * Since: 2.4 **/ diff --git a/libgimpwidgets/gimpwidgetsutils.c b/libgimpwidgets/gimpwidgetsutils.c index 12062ae35f..47f16ab8e3 100644 --- a/libgimpwidgets/gimpwidgetsutils.c +++ b/libgimpwidgets/gimpwidgetsutils.c @@ -474,7 +474,8 @@ monitor_number (GdkMonitor *monitor) * * Since: 3.0 * - * Returns: (transfer full): the monitor's #GimpColorProfile, or %NULL. + * Returns: (nullable) (transfer full): the monitor's #GimpColorProfile, + * or %NULL. **/ GimpColorProfile * gimp_monitor_get_color_profile (GdkMonitor *monitor) @@ -590,7 +591,8 @@ gimp_monitor_get_color_profile (GdkMonitor *monitor) * * Since: 3.0 * - * Returns: (transfer full): @widget's monitor's #GimpColorProfile, or %NULL. + * Returns: (nullable) (transfer full): @widget's monitor's #GimpColorProfile, + * or %NULL. **/ GimpColorProfile * gimp_widget_get_color_profile (GtkWidget *widget) diff --git a/plug-ins/file-jpeg/jpeg-settings.c b/plug-ins/file-jpeg/jpeg-settings.c index af33e846e9..65a2d216b6 100644 --- a/plug-ins/file-jpeg/jpeg-settings.c +++ b/plug-ins/file-jpeg/jpeg-settings.c @@ -264,7 +264,7 @@ jpeg_restore_original_settings (gint32 image_ID, * no parasite exists or if it cannot be used, this function returns * NULL. * - * Returns: an array of quantization tables, or NULL. + * Returns: (nullable): an array of quantization tables, or NULL. */ guint ** jpeg_restore_original_tables (gint32 image_ID,