Commit 5f92ced1 authored by Niels De Graef's avatar Niels De Graef Committed by Jehan

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.
parent 1dda6015
Pipeline #101132 passed with stages
in 15 minutes and 26 seconds
......@@ -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 *
......
......@@ -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)
......
......@@ -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)
......
......@@ -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)
......
......@@ -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)
......
......@@ -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,
......
......@@ -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 *
......
......@@ -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,
......
......@@ -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 *
......
......@@ -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
**/
......
......@@ -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
**/
......
......@@ -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
......
......@@ -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.
*
......
......@@ -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
......
......@@ -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
**/
......
......@@ -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
**/
......
......@@ -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
**/
......
......@@ -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
**/
......
......@@ -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 *
......
......@@ -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
*/
......
......@@ -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
**/
......
......@@ -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)
......
......@@ -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,
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment