[gtk/matthiasc/for-master: 31/41] gdk: Cosmetic docs changes

[Matthias Clasen <matthiasc src gnome org>]

commit 6cb4dda5d619d6c19535a649ff7782ee76d12dff
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat May 22 14:43:11 2021 -0400

    gdk: Cosmetic docs changes

 gdk/gdk.c                    |  1 +
 gdk/gdkcairo.c               |  2 +-
 gdk/gdkcairocontext.c        |  9 ++++-----
 gdk/gdkclipboard.c           | 10 +++++-----
 gdk/gdkcontentdeserializer.c | 12 ++++++------
 gdk/gdkcontentformats.c      |  6 +++---
 gdk/gdkcontentserializer.c   |  4 ++--
 7 files changed, 22 insertions(+), 22 deletions(-)
---
diff --git a/gdk/gdk.c b/gdk/gdk.c
index 0607d8f8e2..f3e2336f50 100644
--- a/gdk/gdk.c
+++ b/gdk/gdk.c
@@ -87,6 +87,7 @@
  * GDK_DISABLE_DEPRECATION_WARNINGS:
  *
  * A macro that should be defined before including the gdk.h header.
+ *
  * If it is defined, no compiler warnings will be produced for uses
  * of deprecated GDK APIs.
  */
diff --git a/gdk/gdkcairo.c b/gdk/gdkcairo.c
index 955a31cbf1..d728fec56f 100644
--- a/gdk/gdkcairo.c
+++ b/gdk/gdkcairo.c
@@ -287,7 +287,7 @@ _gdk_cairo_surface_extents (cairo_surface_t *surface,
  * This function takes into account device offsets that might be
  * set with cairo_surface_set_device_offset().
  *
- * Returns: A `cairo_region_t`; must be freed with cairo_region_destroy()
+ * Returns: (transfer full): A `cairo_region_t`
  */
 cairo_region_t *
 gdk_cairo_region_create_from_surface (cairo_surface_t *surface)
diff --git a/gdk/gdkcairocontext.c b/gdk/gdkcairocontext.c
index 995ade74a4..8f611eeef4 100644
--- a/gdk/gdkcairocontext.c
+++ b/gdk/gdkcairocontext.c
@@ -34,8 +34,8 @@
  * draw context.
  *
  * `GdkCairoContext`s are created for a surface using
- * [method@Gdk.Surface.create_cairo_context], and the context can then be used
- * to draw on that surface.
+ * [method@Gdk.Surface.create_cairo_context], and the context
+ * can then be used to draw on that surface.
  */
 
 typedef struct _GdkCairoContextPrivate GdkCairoContextPrivate;
@@ -70,9 +70,8 @@ gdk_cairo_context_init (GdkCairoContext *self)
  * The returned context is guaranteed to be valid until
  * [method@Gdk.DrawContext.end_frame] is called.
  *
- * Returns: (transfer full) (nullable): a Cairo context to be used
- *   to draw the contents of the `GdkSurface`. %NULL is returned
- *   when @context is not drawing.
+ * Returns: (transfer full) (nullable): a Cairo context
+ *   to draw on `GdkSurface
  */
 cairo_t *
 gdk_cairo_context_cairo_create (GdkCairoContext *self)
diff --git a/gdk/gdkclipboard.c b/gdk/gdkclipboard.c
index 18b5b7b490..cce1f545f7 100644
--- a/gdk/gdkclipboard.c
+++ b/gdk/gdkclipboard.c
@@ -520,8 +520,8 @@ gdk_clipboard_get_content (GdkClipboard *clipboard)
 /**
  * gdk_clipboard_store_async:
  * @clipboard: a `GdkClipboard`
- * @io_priority: the I/O priority of the request.
- * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore.
+ * @io_priority: the I/O priority of the request
+ * @cancellable: (nullable): optional `GCancellable` object
  * @callback: (scope async): callback to call when the request is satisfied
  * @user_data: (closure): the data to pass to callback function
  *
@@ -637,7 +637,7 @@ gdk_clipboard_read_internal (GdkClipboard        *clipboard,
  * @clipboard: a `GdkClipboard`
  * @mime_types: a %NULL-terminated array of mime types to choose from
  * @io_priority: the I/O priority of the request
- * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore.
+ * @cancellable: (nullable): optional `GCancellable` object
  * @callback: (scope async): callback to call when the request is satisfied
  * @user_data: (closure): the data to pass to callback function
  *
@@ -676,7 +676,7 @@ gdk_clipboard_read_async (GdkClipboard        *clipboard,
  * gdk_clipboard_read_finish:
  * @clipboard: a `GdkClipboard`
  * @result: a `GAsyncResult`
- * @out_mime_type: (out) (optional) (transfer none): pointer to store
+ * @out_mime_type: (out) (optional) (transfer none): location to store
  *   the chosen mime type
  * @error: a `GError` location to store the error occurring
  *
@@ -960,7 +960,7 @@ gdk_clipboard_read_texture_finish (GdkClipboard  *clipboard,
 /**
  * gdk_clipboard_read_text_async:
  * @clipboard: a `GdkClipboard`
- * @cancellable: (nullable): optional `GCancellable` object, %NULL to ignore
+ * @cancellable: (nullable): optional `GCancellable` object
  * @callback: (scope async): callback to call when the request is satisfied
  * @user_data: (closure): the data to pass to callback function
  *
diff --git a/gdk/gdkcontentdeserializer.c b/gdk/gdkcontentdeserializer.c
index ba0908a47e..f245b4c350 100644
--- a/gdk/gdkcontentdeserializer.c
+++ b/gdk/gdkcontentdeserializer.c
@@ -190,9 +190,9 @@ gdk_content_deserializer_get_mime_type (GdkContentDeserializer *deserializer)
  * gdk_content_deserializer_get_gtype:
  * @deserializer: a `GdkContentDeserializer`
  *
- * Gets the GType to create an instance of.
+ * Gets the `GType` to create an instance of.
  *
- * Returns: the GType for the current operation
+ * Returns: the `GType` for the current operation
  */
 GType
 gdk_content_deserializer_get_gtype (GdkContentDeserializer *deserializer)
@@ -224,7 +224,7 @@ gdk_content_deserializer_get_value (GdkContentDeserializer *deserializer)
  *
  * Gets the input stream for the current operation.
  *
- * This is the stream that was passed to [func@content_deserialize_async].
+ * This is the stream that was passed to [func@Gdk.content_deserialize_async].
  *
  * Returns: (transfer none): the input stream for the current operation
  */
@@ -242,7 +242,7 @@ gdk_content_deserializer_get_input_stream (GdkContentDeserializer *deserializer)
  *
  * Gets the I/O priority for the current operation.
  *
- * This is the priority that was passed to [funccontent_deserialize_async].
+ * This is the priority that was passed to [func@Gdk.content_deserialize_async].
  *
  * Returns: the I/O priority for the current operation
  */
@@ -260,7 +260,7 @@ gdk_content_deserializer_get_priority (GdkContentDeserializer *deserializer)
  *
  * Gets the cancellable for the current operation.
  *
- * This is the `GCancellable` that was passed to [func@content_deserialize_async].
+ * This is the `GCancellable` that was passed to [func@Gdk.content_deserialize_async].
  *
  * Returns: (transfer none): the cancellable for the current operation
  */
@@ -539,7 +539,7 @@ deserialize_not_found (GdkContentDeserializer *deserializer)
  * indicate a higher priority.
  *
  * When the operation is finished, @callback will be called. You must then
- * call [func@content_deserialize_finish] to get the result of the operation.
+ * call [func@Gdk.content_deserialize_finish] to get the result of the operation.
  */
 void
 gdk_content_deserialize_async (GInputStream        *stream,
diff --git a/gdk/gdkcontentformats.c b/gdk/gdkcontentformats.c
index 8a0ca88f7e..1e63488d07 100644
--- a/gdk/gdkcontentformats.c
+++ b/gdk/gdkcontentformats.c
@@ -84,8 +84,8 @@ G_DEFINE_BOXED_TYPE (GdkContentFormats, gdk_content_formats,
  * If @string is not a valid mime type, %NULL is returned instead.
  * See RFC 2048 for the syntax if mime types.
  *
- * Returns: An interned string for the canonicalized mime type
- *   or %NULL if the string wasn't a valid mime type
+ * Returns: (nullable): An interned string for the canonicalized
+ *   mime type or %NULL if the string wasn't a valid mime type
  */
 const char *
 gdk_intern_mime_type (const char *string)
@@ -133,7 +133,7 @@ gdk_content_formats_new_take (GType *      gtypes,
  *
  * The mime types must be valid and different from each other or the
  * behavior of the return value is undefined. If you cannot guarantee
- * this, use `GdkContentFormatsBuilder` instead.
+ * this, use [struct@Gdk.ContentFormatsBuilder] instead.
  *
  * Returns: (transfer full): the new `GdkContentFormats`.
  */
diff --git a/gdk/gdkcontentserializer.c b/gdk/gdkcontentserializer.c
index ccfb033a86..8c5ce6ef54 100644
--- a/gdk/gdkcontentserializer.c
+++ b/gdk/gdkcontentserializer.c
@@ -43,7 +43,7 @@
  *
  * GTK provides serializers and deserializers for common data types
  * such as text, colors, images or file lists. To register your own
- * serialization functions, use [func@content_register_serializer].
+ * serialization functions, use [func@Gdk.content_register_serializer].
  *
  * Also see [class@Gdk.ContentDeserializer].
  */
@@ -543,7 +543,7 @@ serialize_not_found (GdkContentSerializer *serializer)
  * indicate a higher priority.
  *
  * When the operation is finished, @callback will be called. You must then
- * call [func@content_serialize_finish] to get the result of the operation.
+ * call [func@Gdk.content_serialize_finish] to get the result of the operation.
  */
 void
 gdk_content_serialize_async (GOutputStream       *stream,