Commit 4a0d3d7a authored by Matthias Clasen's avatar Matthias Clasen
Browse files

docs: Reduce redundancy

Remove a boatload of "or %NULL" from nullable parameters
and return values. gi-docgen generates suitable text from
the annotation that we don't need to duplicate.

This adds a few missing nullable annotations too.
parent 7fe0610b
Pipeline #284797 passed with stages
in 32 minutes and 7 seconds
......@@ -237,7 +237,7 @@ gdk_app_launch_context_set_timestamp (GdkAppLaunchContext *context,
/**
* gdk_app_launch_context_set_icon:
* @context: a `GdkAppLaunchContext`
* @icon: (nullable): a #GIcon, or %NULL
* @icon: (nullable): a #GIcon
*
* Sets the icon for applications that are launched with this
* context.
......@@ -267,7 +267,7 @@ gdk_app_launch_context_set_icon (GdkAppLaunchContext *context,
/**
* gdk_app_launch_context_set_icon_name:
* @context: a `GdkAppLaunchContext`
* @icon_name: (nullable): an icon name, or %NULL
* @icon_name: (nullable): an icon name
*
* Sets the icon for applications that are launched with this context.
*
......
......@@ -574,7 +574,7 @@ gdk_clipboard_store_async (GdkClipboard *clipboard,
* gdk_clipboard_store_finish:
* @clipboard: a `GdkClipboard`
* @result: a `GAsyncResult`
* @error: a `GError` location to store the error occurring, or %NULL to ignore.
* @error: a `GError` location to store the error occurring
*
* Finishes an asynchronous clipboard store.
*
......@@ -684,7 +684,7 @@ gdk_clipboard_read_async (GdkClipboard *clipboard,
*
* See [method@Gdk.Clipboard.read_async].
*
* Returns: (transfer full) (nullable): a `GInputStream` or %NULL on error
* Returns: (transfer full) (nullable): a `GInputStream`
*/
GInputStream *
gdk_clipboard_read_finish (GdkClipboard *clipboard,
......@@ -872,7 +872,7 @@ gdk_clipboard_read_value_async (GdkClipboard *clipboard,
* gdk_clipboard_read_value_finish:
* @clipboard: a `GdkClipboard`
* @result: a `GAsyncResult`
* @error: a GError` location to store the error occurring, or %NULL to ignore
* @error: a GError` location to store the error occurring
*
* Finishes an asynchronous clipboard read.
*
......@@ -931,13 +931,13 @@ gdk_clipboard_read_texture_async (GdkClipboard *clipboard,
* gdk_clipboard_read_texture_finish:
* @clipboard: a `GdkClipboard`
* @result: a `GAsyncResult`
* @error: a `GError` location to store the error occurring, or %NULL to ignore
* @error: a `GError` location to store the error occurring
*
* Finishes an asynchronous clipboard read.
*
* See [method@Gdk.Clipboard.read_texture_async].
*
* Returns: (transfer full) (nullable): a new `GdkTexture` or %NULL on error
* Returns: (transfer full) (nullable): a new `GdkTexture`
*/
GdkTexture *
gdk_clipboard_read_texture_finish (GdkClipboard *clipboard,
......@@ -996,13 +996,13 @@ gdk_clipboard_read_text_async (GdkClipboard *clipboard,
* gdk_clipboard_read_text_finish:
* @clipboard: a `GdkClipboard`
* @result: a `GAsyncResult`
* @error: a `GError` location to store the error occurring, or %NULL to ignore
* @error: a `GError` location to store the error occurring
*
* Finishes an asynchronous clipboard read.
*
* See [method@Gdk.Clipboard.read_text_async].
*
* Returns: (transfer full) (nullable): a new string or %NULL on error
* Returns: (transfer full) (nullable): a new string
*/
char *
gdk_clipboard_read_text_finish (GdkClipboard *clipboard,
......
......@@ -384,7 +384,7 @@ gdk_content_formats_match_gtype (const GdkContentFormats *first,
*
* If no matching mime type is found, %NULL is returned.
*
* Returns: (nullable): The first common mime type or %NULL if none.
* Returns: (nullable): The first common mime type or %NULL if none
*/
const char *
gdk_content_formats_match_mime_type (const GdkContentFormats *first,
......
......@@ -319,7 +319,7 @@ gdk_content_provider_write_mime_type_async (GdkContentProvider *provider,
* gdk_content_provider_write_mime_type_finish:
* @provider: a `GdkContentProvider`
* @result: a `GAsyncResult`
* @error: a `GError` location to store the error occurring, or %NULL to ignore
* @error: a `GError` location to store the error occurring
*
* Finishes an asynchronous write operation.
*
......@@ -343,7 +343,7 @@ gdk_content_provider_write_mime_type_finish (GdkContentProvider *provider,
* gdk_content_provider_get_value:
* @provider: a `GdkContentProvider`
* @value: the `GValue` to fill
* @error: a `GError` location to store the error occurring, or %NULL to ignore
* @error: a `GError` location to store the error occurring
*
* Gets the contents of @provider stored in @value.
*
......
......@@ -379,7 +379,7 @@ gdk_cursor_new_from_texture (GdkTexture *texture,
* it is used on does not support textured cursors.
*
* Returns: (transfer none) (nullable): the fallback of the cursor or %NULL
* to use the default cursor as fallback.
* to use the default cursor as fallback
*/
GdkCursor *
gdk_cursor_get_fallback (GdkCursor *cursor)
......
......@@ -1145,7 +1145,7 @@ _gdk_device_surface_at_position (GdkDevice *device,
* }
* ```
*
* Returns: (nullable): the vendor ID, or %NULL
* Returns: (nullable): the vendor ID
*/
const char *
gdk_device_get_vendor_id (GdkDevice *device)
......@@ -1164,7 +1164,7 @@ gdk_device_get_vendor_id (GdkDevice *device)
* This ID is retrieved from the device, and does not change.
* See [method@Gdk.Device.get_vendor_id] for more information.
*
* Returns: (nullable): the product ID, or %NULL
* Returns: (nullable): the product ID
*/
const char *
gdk_device_get_product_id (GdkDevice *device)
......@@ -1239,7 +1239,7 @@ gdk_device_get_num_touches (GdkDevice *device)
*
* Retrieves the current tool for @device.
*
* Returns: (transfer none): the `GdkDeviceTool`, or %NULL
* Returns: (transfer none): the `GdkDeviceTool`
*/
GdkDeviceTool *
gdk_device_get_device_tool (GdkDevice *device)
......
......@@ -692,7 +692,7 @@ gdk_drag_set_selected_action (GdkDrag *drag,
* drag operation. The surface is owned by @drag and will be destroyed
* when the drag operation is over.
*
* Returns: (nullable) (transfer none): the drag surface, or %NULL
* Returns: (nullable) (transfer none): the drag surface
*/
GdkSurface *
gdk_drag_get_drag_surface (GdkDrag *drag)
......
......@@ -219,7 +219,7 @@ gdk_draw_context_surface_resized (GdkDrawContext *context)
*
* Retrieves the `GdkDisplay` the @context is created for
*
* Returns: (nullable) (transfer none): a `GdkDisplay` or %NULL
* Returns: (nullable) (transfer none): the `GdkDisplay`
*/
GdkDisplay *
gdk_draw_context_get_display (GdkDrawContext *context)
......@@ -237,7 +237,7 @@ gdk_draw_context_get_display (GdkDrawContext *context)
*
* Retrieves the surface that @context is bound to.
*
* Returns: (nullable) (transfer none): a #GdkSurface or %NULL
* Returns: (nullable) (transfer none): the #GdkSurface
*/
GdkSurface *
gdk_draw_context_get_surface (GdkDrawContext *context)
......
......@@ -694,7 +694,7 @@ gdk_drop_read_async (GdkDrop *self,
* @self: a `GdkDrop`
* @result: a `GAsyncResult`
* @out_mime_type: (out) (type utf8): return location for the used mime type
* @error: (nullable): location to store error information on failure, or %NULL
* @error: (nullable): location to store error information on failure
*
* Finishes an async drop read operation.
*
......@@ -705,7 +705,7 @@ gdk_drop_read_async (GdkDrop *self,
*
* See [method@Gdk.Drop.read_async].
*
* Returns: (nullable) (transfer full): the `GInputStream`, or %NULL
* Returns: (nullable) (transfer full): the `GInputStream`
*/
GInputStream *
gdk_drop_read_finish (GdkDrop *self,
......@@ -891,7 +891,7 @@ gdk_drop_read_value_async (GdkDrop *self,
* gdk_drop_read_value_finish:
* @self: a `GdkDrop`
* @result: a `GAsyncResult`
* @error: a `GError` location to store the error occurring, or %NULL to ignore
* @error: a `GError` location to store the error occurring
*
* Finishes an async drop read.
*
......
......@@ -574,9 +574,8 @@ _gdk_event_queue_remove_link (GdkDisplay *display,
* Removes and returns the first event from the event
* queue that is not still being filled in.
*
* Returns: (nullable): the event, or %NULL. Ownership is transferred
* to the caller.
**/
* Returns: (nullable) (transfer full): the event
*/
GdkEvent*
_gdk_event_unqueue (GdkDisplay *display)
{
......@@ -1238,8 +1237,8 @@ gdk_event_get_device (GdkEvent *event)
* the application lifetime, if settings must be stored
* persistently across runs, see [method@Gdk.DeviceTool.get_serial].
*
* Returns: (transfer none) (nullable): The current device tool, or %NULL
**/
* Returns: (transfer none) (nullable): The current device tool
*/
GdkDeviceTool *
gdk_event_get_device_tool (GdkEvent *event)
{
......
......@@ -1127,7 +1127,7 @@ gdk_gl_context_make_current (GdkGLContext *context)
*
* Retrieves the display the @context is created for
*
* Returns: (nullable) (transfer none): a `GdkDisplay` or %NULL
* Returns: (nullable) (transfer none): a `GdkDisplay`
*/
GdkDisplay *
gdk_gl_context_get_display (GdkGLContext *context)
......@@ -1143,7 +1143,7 @@ gdk_gl_context_get_display (GdkGLContext *context)
*
* Retrieves the surface used by the @context.
*
* Returns: (nullable) (transfer none): a `GdkSurface` or %NULL
* Returns: (nullable) (transfer none): a `GdkSurface`
*/
GdkSurface *
gdk_gl_context_get_surface (GdkGLContext *context)
......@@ -1159,7 +1159,7 @@ gdk_gl_context_get_surface (GdkGLContext *context)
*
* Retrieves the `GdkGLContext` that this @context share data with.
*
* Returns: (nullable) (transfer none): a `GdkGLContext` or %NULL
* Returns: (nullable) (transfer none): a `GdkGLContext`
*/
GdkGLContext *
gdk_gl_context_get_shared_context (GdkGLContext *context)
......@@ -1223,7 +1223,7 @@ gdk_gl_context_clear_current (void)
*
* Retrieves the current `GdkGLContext`.
*
* Returns: (nullable) (transfer none): the current `GdkGLContext`, or %NULL
* Returns: (nullable) (transfer none): the current `GdkGLContext`
*/
GdkGLContext *
gdk_gl_context_get_current (void)
......
......@@ -421,8 +421,7 @@ gdk_monitor_get_connector (GdkMonitor *monitor)
* The PNP ID registry is located at
* [https://uefi.org/pnp_id_list](https://uefi.org/pnp_id_list).
*
* Returns: (transfer none) (nullable): the name of the manufacturer,
* or %NULL
* Returns: (transfer none) (nullable): the name of the manufacturer
*/
const char *
gdk_monitor_get_manufacturer (GdkMonitor *monitor)
......@@ -438,7 +437,7 @@ gdk_monitor_get_manufacturer (GdkMonitor *monitor)
*
* Gets the string identifying the monitor model, if available.
*
* Returns: (transfer none) (nullable): the monitor model, or %NULL
* Returns: (transfer none) (nullable): the monitor model
*/
const char *
gdk_monitor_get_model (GdkMonitor *monitor)
......
......@@ -225,8 +225,7 @@ gdk_pixbuf_get_from_surface (cairo_surface_t *surface,
* stages will almost certainly convert the pixbuf back into a texture
* to draw it on screen.
*
* Returns: (transfer full) (nullable): a new #GdkPixbuf or %NULL
* in case of an error
* Returns: (transfer full) (nullable): a new #GdkPixbuf
*/
GdkPixbuf *
gdk_pixbuf_get_from_texture (GdkTexture *texture)
......
......@@ -92,7 +92,7 @@ gdk_rectangle_union (const GdkRectangle *src1,
* @src1: a `GdkRectangle`
* @src2: a `GdkRectangle`
* @dest: (out caller-allocates) (optional): return location for the
* intersection of @src1 and @src2, or %NULL
* intersection of @src1 and @src2
*
* Calculates the intersection of two rectangles.
*
......
......@@ -1164,8 +1164,7 @@ gdk_surface_get_paint_gl_context (GdkSurface *surface,
* Before using the returned `GdkGLContext`, you will need to
* call [method@Gdk.GLContext.make_current] or [method@Gdk.GLContext.realize].
*
* Returns: (transfer full): the newly created `GdkGLContext`,
* or %NULL on error
* Returns: (transfer full) (nullable): the newly created `GdkGLContext`
*/
GdkGLContext *
gdk_surface_create_gl_context (GdkSurface *surface,
......@@ -1696,9 +1695,9 @@ gdk_surface_constrain_size (GdkGeometry *geometry,
* gdk_surface_get_device_position:
* @surface: a `GdkSurface`
* @device: pointer `GdkDevice` to query to
* @x: (out) (optional): return locatio for the X coordinate of @device, or %NULL
* @y: (out) (optional): return location for the Y coordinate of @device, or %NULL
* @mask: (out) (optional): return location for the modifier mask, or %NULL
* @x: (out) (optional): return locatio for the X coordinate of @device
* @y: (out) (optional): return location for the Y coordinate of @device
* @mask: (out) (optional): return location for the modifier mask
*
* Obtains the current device position and modifier state.
*
......@@ -1839,10 +1838,9 @@ gdk_surface_set_cursor_internal (GdkSurface *surface,
* If the return value is %NULL then there is no custom cursor set on
* the surface, and it is using the cursor for its parent surface.
*
* Returns: (nullable) (transfer none): a `GdkCursor`, or %NULL. The
* returned object is owned by the `GdkSurface` and should not be
* unreferenced directly. Use [method@Gdk.Surface.set_cursor] to
* unset the cursor of the surface
* Use [method@Gdk.Surface.set_cursor] to unset the cursor of the surface.
*
* Returns: (nullable) (transfer none): a `GdkCursor`
*/
GdkCursor *
gdk_surface_get_cursor (GdkSurface *surface)
......@@ -1920,10 +1918,9 @@ gdk_surface_set_cursor (GdkSurface *surface,
* If the return value is %NULL then there is no custom cursor set on the
* specified surface, and it is using the cursor for its parent surface.
*
* Returns: (nullable) (transfer none): a `GdkCursor`, or %NULL. The
* returned object is owned by the `GdkSurface` and should not be
* unreferenced directly. Use [method@Gdk.Surface.set_cursor] to unset
* the cursor of the surface
* Use [method@Gdk.Surface.set_cursor] to unset the cursor of the surface.
*
* Returns: (nullable) (transfer none): a `GdkCursor`
*/
GdkCursor *
gdk_surface_get_device_cursor (GdkSurface *surface,
......@@ -2415,8 +2412,7 @@ gdk_surface_destroy_notify (GdkSurface *surface)
* the source if [method@Gdk.Drag.get_selected_action] returns
* %GDK_ACTION_MOVE.
*
* Returns: (transfer full) (nullable): a newly created [class@Gdk.Drag]
* or %NULL on error
* Returns: (transfer full) (nullable): a newly created `GdkDrag`
*/
GdkDrag *
gdk_drag_begin (GdkSurface *surface,
......@@ -2624,7 +2620,8 @@ gdk_surface_get_scale_factor (GdkSurface *surface)
/**
* gdk_surface_set_opaque_region:
* @surface: a top-level `GdkSurface`
* @region: (nullable): a region, or %NULL
* @region: (nullable): a region, or %NULL to make the entire
* surface opaque
*
* Marks a region of the `GdkSurface` as opaque.
*
......
......@@ -353,7 +353,7 @@ gdk_texture_new_from_resource (const char *resource_path)
*
* If %NULL is returned, then @error will be set.
*
* Return value: A newly-created `GdkTexture` or %NULL if an error occurred.
* Return value: A newly-created `GdkTexture`
*/
GdkTexture *
gdk_texture_new_from_file (GFile *file,
......
......@@ -818,7 +818,7 @@ gdk_wayland_display_get_next_serial (GdkDisplay *display)
* Gets the startup notification ID for a Wayland display, or %NULL
* if no ID has been defined.
*
* Returns: (nullable): the startup notification ID for @display, or %NULL
* Returns: (nullable): the startup notification ID for @display
*/
const char *
gdk_wayland_display_get_startup_notification_id (GdkDisplay *display)
......
......@@ -2001,9 +2001,9 @@ gdk_x11_lookup_xdisplay (Display *xdisplay)
* Given the root window ID of one of the screen’s of a #GdkDisplay,
* finds the screen.
*
* Returns: (transfer none): the #GdkX11Screen corresponding to
* @xrootwin, or %NULL.
**/
* Returns: (transfer none) (nullable): the #GdkX11Screen
* corresponding to @xrootwin
*/
GdkX11Screen *
_gdk_x11_display_screen_for_xrootwin (GdkDisplay *display,
Window xrootwin)
......
......@@ -290,8 +290,7 @@ _gdk_x11_screen_init_visuals (GdkX11Screen *x11_screen,
*
* Looks up the #GdkVisual for a particular screen and X Visual ID.
*
* Returns: (transfer none) (type GdkX11Visual): the #GdkVisual (owned by the screen
* object), or %NULL if the visual ID wasn’t found.
* Returns: (transfer none) (nullable) (type GdkX11Visual): the #GdkVisual
*/
GdkX11Visual *
gdk_x11_screen_lookup_visual (GdkX11Screen *x11_screen,
......
......@@ -578,8 +578,7 @@ gsk_gl_shader_get_source (GskGLShader *shader)
* Gets the resource path for the GLSL sourcecode being used
* to render this shader.
*
* Returns: (transfer none): The resource path for the shader,
* or %NULL if none.
* Returns: (transfer none) (nullable): The resource path for the shader
*/
const char *
gsk_gl_shader_get_resource (GskGLShader *shader)
......
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