[gtk/ebassi/gidocgen: 100/200] gdk: Some more tweaks of the docs

From: Emmanuele Bassi <ebassi src gnome org>
To: commits-list gnome org
Cc:
Subject: [gtk/ebassi/gidocgen: 100/200] gdk: Some more tweaks of the docs
Date: Thu, 25 Feb 2021 13:08:20 +0000 (UTC)

commit b3cc21cc726b50834905f376ffde8fcf07642276
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun Feb 21 09:19:37 2021 -0500

    gdk: Some more tweaks of the docs

 gdk/gdkcairo.c           |   4 +-
 gdk/gdkdevicepad.c       |   5 +-
 gdk/gdkdisplay.c         | 257 ++++++++++++++++++++++++-----------------------
 gdk/gdkgl.c              |  14 +--
 gdk/gdkkeys.c            |   8 +-
 gdk/gdkkeyuni.c          |  19 ++--
 gdk/gdkpango.c           |  42 ++++----
 gdk/gdkpixbuf-drawable.c |  28 ++----
 gdk/gdktypes.h           |  12 ++-
 9 files changed, 199 insertions(+), 190 deletions(-)
---
diff --git a/gdk/gdkcairo.c b/gdk/gdkcairo.c
index e36d08fefb..3db47ac755 100644
--- a/gdk/gdkcairo.c
+++ b/gdk/gdkcairo.c
@@ -281,13 +281,13 @@ _gdk_cairo_surface_extents (cairo_surface_t *surface,
  * gdk_cairo_region_create_from_surface:
  * @surface: a cairo surface
  *
- * Creates region that describes covers the area where the given
+ * Creates region that covers the area where the given
  * @surface is more than 50% opaque.
  *
  * 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: A `cairo_region_t`; must be freed with cairo_region_destroy()
  */
 cairo_region_t *
 gdk_cairo_region_create_from_surface (cairo_surface_t *surface)
diff --git a/gdk/gdkdevicepad.c b/gdk/gdkdevicepad.c
index ac25d0a873..16ed4d58f9 100644
--- a/gdk/gdkdevicepad.c
+++ b/gdk/gdkdevicepad.c
@@ -21,8 +21,9 @@
  * GdkDevicePad:
  *
  * `GdkDevicePad` is an interface implemented by devices of type
- * %GDK_SOURCE_TABLET_PAD, it allows querying the features provided
- * by the pad device.
+ * %GDK_SOURCE_TABLET_PAD
+ *
+ * It allows querying the features provided by the pad device.
  *
  * Tablet pads may contain one or more groups, each containing a subset
  * of the buttons/rings/strips available. [method@Gdk.DevicePad.get_n_groups]
diff --git a/gdk/gdkdisplay.c b/gdk/gdkdisplay.c
index 9942ec6063..af2dc50b8e 100644
--- a/gdk/gdkdisplay.c
+++ b/gdk/gdkdisplay.c
@@ -39,30 +39,24 @@
 #include <glib.h>
 
 /**
- * SECTION:gdkdisplay
- * @Short_description: Controls a set of monitors and their associated input devices
- * @Title: GdkDisplay
+ * GdkDisplay:
  *
- * GdkDisplay objects are the GDK representation of a workstation.
+ * `GdkDisplay` objects are the GDK representation of a workstation.
  *
  * Their purpose are two-fold:
+ *
  * - To manage and provide information about input devices (pointers, keyboards, etc)
  * - To manage and provide information about output devices (monitors, projectors, etc)
  *
- * Most of the input device handling has been factored out into separate #GdkSeat
- * objects. Every display has a one or more seats, which can be accessed with
- * gdk_display_get_default_seat() and gdk_display_list_seats().
+ * Most of the input device handling has been factored out into separate
+ * [class Gdk Seat] objects. Every display has a one or more seats, which
+ * can be accessed with [method@Gdk.Display.get_default_seat] and
+ * [method@Gdk.Display.list_seats].
  *
- * Output devices are represented by #GdkMonitor objects, which can be accessed
- * with gdk_display_get_monitor_at_surface() and similar APIs.
+ * Output devices are represented by [class@Gdk.Monitor] objects, which can
+ * be accessed with [method@Gdk.Display.get_monitor_at_surface] and similar APIs.
  */
 
-/**
- * GdkDisplay:
- *
- * The GdkDisplay struct contains only private fields and should not
- * be accessed directly.
- */
 enum
 {
   PROP_0,
@@ -158,7 +152,8 @@ gdk_display_class_init (GdkDisplayClass *class)
    * GdkDisplay:composited:
    *
    * %TRUE if the display properly composites the alpha channel.
-   * See gdk_display_is_composited() for details.
+   *
+   * See [method@Gdk.Display.is_composited] for details.
    */
   props[PROP_COMPOSITED] =
     g_param_spec_boolean ("composited",
@@ -170,8 +165,9 @@ gdk_display_class_init (GdkDisplayClass *class)
   /**
    * GdkDisplay:rgba:
    *
-   * %TRUE if the display supports an alpha channel. See gdk_display_is_rgba()
-   * for details.
+   * %TRUE if the display supports an alpha channel.
+   *
+   * See [method@Gdk.Display.is_rgba] for details.
    */
   props[PROP_RGBA] =
     g_param_spec_boolean ("rgba",
@@ -183,8 +179,9 @@ gdk_display_class_init (GdkDisplayClass *class)
   /**
    * GdkDisplay:input-shapes:
    *
-   * %TRUE if the display supports input shapes. See
-   * gdk_display_supports_input_shapes() for details.
+   * %TRUE if the display supports input shapes.
+   *
+   * See [method@Gdk.Display.supports_input_shapes] for details.
    */
   props[PROP_INPUT_SHAPES] =
     g_param_spec_boolean ("input-shapes",
@@ -199,8 +196,7 @@ gdk_display_class_init (GdkDisplayClass *class)
    * GdkDisplay::opened:
    * @display: the object on which the signal is emitted
    *
-   * The ::opened signal is emitted when the connection to the windowing
-   * system for @display is opened.
+   * Emitted when the connection to the windowing system for @display is opened.
    */
   signals[OPENED] =
     g_signal_new (g_intern_static_string ("opened"),
@@ -216,9 +212,8 @@ gdk_display_class_init (GdkDisplayClass *class)
    * @display: the object on which the signal is emitted
    * @is_error: %TRUE if the display was closed due to an error
    *
-   * The ::closed signal is emitted when the connection to the windowing
-   * system for @display is closed.
-   */   
+   * Emitted when the connection to the windowing system for @display is closed.
+   */
   signals[CLOSED] =
     g_signal_new (g_intern_static_string ("closed"),
                  G_OBJECT_CLASS_TYPE (object_class),
@@ -235,8 +230,7 @@ gdk_display_class_init (GdkDisplayClass *class)
    * @display: the object on which the signal is emitted
    * @seat: the seat that was just added
    *
-   * The ::seat-added signal is emitted whenever a new seat is made
-   * known to the windowing system.
+   * Emitted whenever a new seat is made known to the windowing system.
    */
   signals[SEAT_ADDED] =
     g_signal_new (g_intern_static_string ("seat-added"),
@@ -251,8 +245,7 @@ gdk_display_class_init (GdkDisplayClass *class)
    * @display: the object on which the signal is emitted
    * @seat: the seat that was just removed
    *
-   * The ::seat-removed signal is emitted whenever a seat is removed
-   * by the windowing system.
+   * Emitted whenever a seat is removed by the windowing system.
    */
   signals[SEAT_REMOVED] =
     g_signal_new (g_intern_static_string ("seat-removed"),
@@ -267,8 +260,7 @@ gdk_display_class_init (GdkDisplayClass *class)
    * @display: the object on which the signal is emitted
    * @setting: the name of the setting that changed
    *
-   * The ::setting-changed signal is emitted whenever a setting
-   * changes its value.
+   * Emitted whenever a setting changes its value.
    */
   signals[SETTING_CHANGED] =
     g_signal_new (g_intern_static_string ("setting-changed"),
@@ -356,10 +348,11 @@ gdk_display_finalize (GObject *object)
 
 /**
  * gdk_display_close:
- * @display: a #GdkDisplay
+ * @display: a `GdkDisplay`
+ *
+ * Closes the connection to the windowing system for the given display.
  *
- * Closes the connection to the windowing system for the given display,
- * and cleans up associated resources.
+ * This cleans up associated resources.
  */
 void
 gdk_display_close (GdkDisplay *display)
@@ -379,7 +372,7 @@ gdk_display_close (GdkDisplay *display)
 
 /**
  * gdk_display_is_closed:
- * @display: a #GdkDisplay
+ * @display: a `GdkDisplay`
  *
  * Finds out if the display has been closed.
  *
@@ -395,12 +388,12 @@ gdk_display_is_closed  (GdkDisplay  *display)
 
 /*<private>
  * gdk_display_get_event:
- * @display: a #GdkDisplay
+ * @display: a `GdkDisplay`
  *
- * Gets the next #GdkEvent to be processed for @display, fetching events from the
+ * Gets the next `GdkEvent` to be processed for @display, fetching events from the
  * windowing system if necessary.
  *
- * Returns: (nullable) (transfer full): the next #GdkEvent to be processed,
+ * Returns: (nullable) (transfer full): the next `GdkEvent` to be processed,
  *   or %NULL if no events are pending
  */
 GdkEvent *
@@ -416,8 +409,8 @@ gdk_display_get_event (GdkDisplay *display)
 
 /**
  * gdk_display_put_event:
- * @display: a #GdkDisplay
- * @event: (transfer none): a #GdkEvent
+ * @display: a `GdkDisplay`
+ * @event: (transfer none): a `GdkEvent`
  *
  * Appends the given event onto the front of the event
  * queue for @display.
@@ -853,13 +846,13 @@ gdk_device_grab_info (GdkDisplay  *display,
 
 /**
  * gdk_display_device_is_grabbed:
- * @display: a #GdkDisplay
- * @device: a #GdkDevice
+ * @display: a `GdkDisplay`
+ * @device: a `GdkDevice`
  *
  * Returns %TRUE if there is an ongoing grab on @device for @display.
  *
  * Returns: %TRUE if there is a grab in effect for @device.
- **/
+ */
 gboolean
 gdk_display_device_is_grabbed (GdkDisplay *display,
                                GdkDevice  *device)
@@ -879,12 +872,12 @@ gdk_display_device_is_grabbed (GdkDisplay *display,
 
 /**
  * gdk_display_get_name:
- * @display: a #GdkDisplay
+ * @display: a `GdkDisplay`
  *
  * Gets the name of the display.
  *
  * Returns: a string representing the display name. This string is owned
- * by GDK and should not be modified or freed.
+ *   by GDK and should not be modified or freed.
  */
 const char *
 gdk_display_get_name (GdkDisplay *display)
@@ -896,7 +889,7 @@ gdk_display_get_name (GdkDisplay *display)
 
 /**
  * gdk_display_beep:
- * @display: a #GdkDisplay
+ * @display: a `GdkDisplay`
  *
  * Emits a short beep on @display
  */
@@ -910,14 +903,15 @@ gdk_display_beep (GdkDisplay *display)
 
 /**
  * gdk_display_sync:
- * @display: a #GdkDisplay
+ * @display: a `GdkDisplay`
  *
  * Flushes any requests queued for the windowing system and waits until all
- * requests have been handled. This is often used for making sure that the
- * display is synchronized with the current state of the program. Calling
- * gdk_display_sync() before gdk_x11_display_error_trap_pop() makes sure
- * that any errors generated from earlier requests are handled before the
- * error trap is removed.
+ * requests have been handled.
+ *
+ * This is often used for making sure that the display is synchronized
+ * with the current state of the program. Calling [method Gdk Display sync]
+ * before [method@GdkX11.Display.error_trap_pop] makes sure that any errors
+ * generated from earlier requests are handled before the error trap is removed.
  *
  * This is most useful for X11. On windowing systems where requests are
  * handled synchronously, this function will do nothing.
@@ -932,12 +926,13 @@ gdk_display_sync (GdkDisplay *display)
 
 /**
  * gdk_display_flush:
- * @display: a #GdkDisplay
+ * @display: a `GdkDisplay`
  *
- * Flushes any requests queued for the windowing system; this happens automatically
- * when the main loop blocks waiting for new events, but if your application
- * is drawing without returning control to the main loop, you may need
- * to call this function explicitly. A common case where this function
+ * Flushes any requests queued for the windowing system.
+ *
+ * This happens automatically when the main loop blocks waiting for new events,
+ * but if your application is drawing without returning control to the main loop,
+ * you may need to call this function explicitly. A common case where this function
  * needs to be called is when an application is executing drawing commands
  * from a thread other than the thread where the main loop is running.
  *
@@ -954,7 +949,7 @@ gdk_display_flush (GdkDisplay *display)
 
 /**
  * gdk_display_get_clipboard:
- * @display: a #GdkDisplay
+ * @display: a `GdkDisplay`
  *
  * Gets the clipboard used for copy/paste operations.
  *
@@ -973,11 +968,12 @@ gdk_display_get_clipboard (GdkDisplay *display)
 
 /**
  * gdk_display_get_primary_clipboard:
- * @display: a #GdkDisplay
+ * @display: a `GdkDisplay`
  *
- * Gets the clipboard used for the primary selection. On backends where the
- * primary clipboard is not supported natively, GDK emulates this clipboard
- * locally.
+ * Gets the clipboard used for the primary selection.
+ *
+ * On backends where the primary clipboard is not supported natively,
+ * GDK emulates this clipboard locally.
  *
  * Returns: (transfer none): the primary clipboard
  */
@@ -994,9 +990,11 @@ gdk_display_get_primary_clipboard (GdkDisplay *display)
 
 /**
  * gdk_display_supports_input_shapes:
- * @display: a #GdkDisplay
+ * @display: a `GdkDisplay`
  *
- * Returns %TRUE if gdk_surface_set_input_region() can
+ * Returns %TRUE if the display supports input shapes.
+ *
+ * This means that [method@Gdk.Surface.set_input_region] can
  * be used to modify the input shape of surfaces on @display.
  *
  * On modern displays, this value is always %TRUE.
@@ -1039,12 +1037,12 @@ gdk_display_real_get_app_launch_context (GdkDisplay *display)
 
 /**
  * gdk_display_get_app_launch_context:
- * @display: a #GdkDisplay
+ * @display: a `GdkDisplay`
  *
- * Returns a #GdkAppLaunchContext suitable for launching
+ * Returns a `GdkAppLaunchContext` suitable for launching
  * applications on the given display.
  *
- * Returns: (transfer full): a new #GdkAppLaunchContext for @display.
+ * Returns: (transfer full): a new `GdkAppLaunchContext` for @display.
  *     Free with g_object_unref() when done
  */
 GdkAppLaunchContext *
@@ -1061,7 +1059,7 @@ gdk_display_get_app_launch_context (GdkDisplay *display)
  *
  * Opens a display.
  *
- * Returns: (nullable) (transfer none): a #GdkDisplay, or %NULL if the
+ * Returns: (nullable) (transfer none): a `GdkDisplay`, or %NULL if the
  *     display could not be opened
  */
 GdkDisplay *
@@ -1079,17 +1077,17 @@ _gdk_display_get_next_serial (GdkDisplay *display)
 
 /**
  * gdk_display_notify_startup_complete:
- * @display: a #GdkDisplay
+ * @display: a `GdkDisplay`
  * @startup_id: a startup-notification identifier, for which
  *     notification process should be completed
  *
  * Indicates to the GUI environment that the application has
  * finished loading, using a given identifier.
  *
- * GTK will call this function automatically for #GtkWindow
+ * GTK will call this function automatically for [class@Gtk.Window]
  * with custom startup-notification identifier unless
- * gtk_window_set_auto_startup_notification() is called to
- * disable that feature.
+ * [method@Gtk.Window.set_auto_startup_notification]
+ * is called to disable that feature.
  */
 void
 gdk_display_notify_startup_complete (GdkDisplay  *display,
@@ -1102,7 +1100,7 @@ gdk_display_notify_startup_complete (GdkDisplay  *display,
 
 /**
  * gdk_display_get_startup_notification_id:
- * @display: a #GdkDisplay
+ * @display: a `GdkDisplay`
  *
  * Gets the startup notification ID for a Wayland display, or %NULL
  * if no ID has been defined.
@@ -1151,7 +1149,7 @@ gdk_display_create_surface (GdkDisplay     *display,
 
 /**
  * gdk_display_get_keymap:
- * @display: the #GdkDisplay
+ * @display: the `GdkDisplay`
  *
  * Returns the #GdkKeymap attached to @display.
  *
@@ -1195,21 +1193,23 @@ gdk_display_set_debug_flags (GdkDisplay    *display,
 
 /**
  * gdk_display_is_composited:
- * @display: a #GdkDisplay
+ * @display: a `GdkDisplay`
  *
  * Returns whether surfaces can reasonably be expected to have
- * their alpha channel drawn correctly on the screen. Check
- * gdk_display_is_rgba() for whether the display supports an
- * alpha channel.
+ * their alpha channel drawn correctly on the screen.
+ *
+ * Check [method@Gdk.Display.is_rgba] for whether the display
+ * supports an alpha channel.
  *
  * On X11 this function returns whether a compositing manager is
  * compositing on @display.
  *
  * On modern displays, this value is always %TRUE.
  *
- * Returns: Whether surfaces with RGBA visuals can reasonably be
- * expected to have their alpha channels drawn correctly on the screen.
- **/
+ * Returns: Whether surfaces with RGBA visuals can reasonably
+ *   be expected to have their alpha channels drawn correctly
+ *   on the screen.
+ */
 gboolean
 gdk_display_is_composited (GdkDisplay *display)
 {
@@ -1234,7 +1234,7 @@ gdk_display_set_composited (GdkDisplay *display,
 
 /**
  * gdk_display_is_rgba:
- * @display: a #GdkDisplay
+ * @display: a `GdkDisplay`
  *
  * Returns whether surfaces on this @display are created with an
  * alpha channel.
@@ -1243,14 +1243,14 @@ gdk_display_set_composited (GdkDisplay *display,
  * surface’s alpha channel won’t be honored when displaying the
  * surface on the screen: in particular, for X an appropriate
  * windowing manager and compositing manager must be running to
- * provide appropriate display. Use gdk_display_is_composited()
+ * provide appropriate display. Use [method@Gdk.Display.is_composited]
  * to check if that is the case.
  *
  * On modern displays, this value is always %TRUE.
  *
  * Returns: %TRUE if surfaces are created with an alpha channel or
  *     %FALSE if the display does not support this functionality.
- **/
+ */
 gboolean
 gdk_display_is_rgba (GdkDisplay *display)
 {
@@ -1321,9 +1321,9 @@ gdk_display_remove_seat (GdkDisplay *display,
 
 /**
  * gdk_display_get_default_seat:
- * @display: a #GdkDisplay
+ * @display: a `GdkDisplay`
  *
- * Returns the default #GdkSeat for this display.
+ * Returns the default `GdkSeat` for this display.
  *
  * Note that a display may not have a seat. In this case,
  * this function will return %NULL.
@@ -1344,12 +1344,12 @@ gdk_display_get_default_seat (GdkDisplay *display)
 
 /**
  * gdk_display_list_seats:
- * @display: a #GdkDisplay
+ * @display: a `GdkDisplay`
  *
  * Returns the list of seats known to @display.
  *
  * Returns: (transfer container) (element-type GdkSeat): the
- *          list of seats known to the #GdkDisplay
+ *          list of seats known to the `GdkDisplay`
  **/
 GList *
 gdk_display_list_seats (GdkDisplay *display)
@@ -1361,17 +1361,17 @@ gdk_display_list_seats (GdkDisplay *display)
 
 /**
  * gdk_display_get_monitors:
- * @self: a #GdkDisplay
+ * @self: a `GdkDisplay`
  *
  * Gets the list of monitors associated with this display.
  *
- * Subsequent calls to this function will always return the same list for the
- * same display.
+ * Subsequent calls to this function will always return the
+ * same list for the same display.
  *
- * You can listen to the GListModel::items-changed signal on this list
- * to monitor changes to the monitor of this display.
+ * You can listen to the GListModel::items-changed signal on
+ * this list to monitor changes to the monitor of this display.
  *
- * Returns: (transfer none): a #GListModel of #GdkMonitor
+ * Returns: (transfer none): a #GListModel of `GdkMonitor`
  */
 GListModel *
 gdk_display_get_monitors (GdkDisplay *self)
@@ -1383,14 +1383,17 @@ gdk_display_get_monitors (GdkDisplay *self)
 
 /**
  * gdk_display_get_monitor_at_surface:
- * @display: a #GdkDisplay
- * @surface: a #GdkSurface
+ * @display: a `GdkDisplay`
+ * @surface: a `GdkSurface`
  *
  * Gets the monitor in which the largest area of @surface
- * resides, or a monitor close to @surface if it is outside
+ * resides.
+ *
+ * Returns a monitor close to @surface if it is outside
  * of all monitors.
  *
- * Returns: (transfer none): the monitor with the largest overlap with @surface
+ * Returns: (transfer none): the monitor with the largest
+ *   overlap with @surface
  */
 GdkMonitor *
 gdk_display_get_monitor_at_surface (GdkDisplay *display,
@@ -1448,7 +1451,7 @@ gdk_display_emit_opened (GdkDisplay *display)
 
 /**
  * gdk_display_get_setting:
- * @display: a #GdkDisplay
+ * @display: a `GdkDisplay`
  * @name: the name of the setting
  * @value: location to store the value of the setting
  *
@@ -1502,23 +1505,24 @@ gdk_display_set_cursor_theme (GdkDisplay *display,
 
 /**
  * gdk_display_map_keyval:
- * @display: a #GdkDisplay
+ * @display: a `GdkDisplay`
  * @keyval: a keyval, such as %GDK_KEY_a, %GDK_KEY_Up, %GDK_KEY_Return, etc.
  * @keys: (out) (array length=n_keys) (transfer full): return location
- *     for an array of #GdkKeymapKey
+ *     for an array of `GdkKeymapKey`
  * @n_keys: return location for number of elements in returned array
  *
  * Obtains a list of keycode/group/level combinations that will
- * generate @keyval. Groups and levels are two kinds of keyboard mode;
- * in general, the level determines whether the top or bottom symbol
- * on a key is used, and the group determines whether the left or
- * right symbol is used.
+ * generate @keyval.
+ *
+ * Groups and levels are two kinds of keyboard mode; in general, the level
+ * determines whether the top or bottom symbol on a key is used, and the
+ * group determines whether the left or right symbol is used.
  *
  * On US keyboards, the shift key changes the keyboard level, and there
  * are no groups. A group switch key might convert a keyboard between
  * Hebrew to English modes, for example.
  *
- * #GdkEventKey contains a %group field that indicates the active
+ * `GdkEventKey` contains a %group field that indicates the active
  * keyboard group. The level is computed from the modifier mask.
  *
  * The returned array should be freed with g_free().
@@ -1539,16 +1543,17 @@ gdk_display_map_keyval (GdkDisplay    *display,
 
 /**
  * gdk_display_map_keycode:
- * @display: a #GdkDisplay
+ * @display: a `GdkDisplay`
  * @keycode: a keycode
  * @keys: (out) (array length=n_entries) (transfer full) (optional): return
- *     location for array of #GdkKeymapKey, or %NULL
+ *     location for array of `GdkKeymapKey`, or %NULL
  * @keyvals: (out) (array length=n_entries) (transfer full) (optional): return
  *     location for array of keyvals, or %NULL
  * @n_entries: length of @keys and @keyvals
  *
- * Returns the keyvals bound to @keycode. The Nth #GdkKeymapKey
- * in @keys is bound to the Nth keyval in @keyvals.
+ * Returns the keyvals bound to @keycode.
+ *
+ * The Nth `GdkKeymapKey` in @keys is bound to the Nth keyval in @keyvals.
  *
  * When a keycode is pressed by the user, the keyval from
  * this list of entries is selected by considering the effective
@@ -1574,7 +1579,7 @@ gdk_display_map_keycode (GdkDisplay    *display,
 
 /**
  * gdk_display_translate_key:
- * @display: a #GdkDisplay
+ * @display: a `GdkDisplay`
  * @keycode: a keycode
  * @state: a modifier state
  * @group: active keyboard group
@@ -1585,23 +1590,25 @@ gdk_display_map_keycode (GdkDisplay    *display,
  * @consumed: (out) (optional): return location for modifiers
  *     that were used to determine the group or level, or %NULL
  *
- * Translates the contents of a #GdkEventKey (ie @keycode, @state, and @group)
- * into a keyval, effective group, and level. Modifiers that affected the
- * translation and are thus unavailable for application use are returned in
- * @consumed_modifiers.
+ * Translates the contents of a `GdkEventKey` into a keyval, effective group,
+ * and level.
+ *
+ * Modifiers that affected the translation and are thus unavailable for
+ * application use are returned in @consumed_modifiers.
  *
- * The @effective_group is the group that was actually used for the translation;
- * some keys such as Enter are not affected by the active keyboard group.
- * The @level is derived from @state.
+ * The @effective_group is the group that was actually used for the
+ * translation; some keys such as Enter are not affected by the active
+ * keyboard group. The @level is derived from @state.
  *
- * @consumed_modifiers gives modifiers that should be masked outfrom @state
- * when comparing this key press to a keyboard shortcut. For instance, on a US
- * keyboard, the `plus` symbol is shifted, so when comparing a key press to a
- * `<Control>plus` accelerator `<Shift>` should be masked out.
+ * @consumed_modifiers gives modifiers that should be masked out
+ * from @state when comparing this key press to a keyboard shortcut.
+ * For instance, on a US keyboard, the `plus` symbol is shifted, so
+ * when comparing a key press to a `<Control>plus` accelerator `<Shift>`
+ * should be masked out.
  *
- * This function should rarely be needed, since #GdkEventKey already contains
- * the translated keyval. It is exported for the benefit of virtualized test
- * environments.
+ * This function should rarely be needed, since `GdkEventKey` already
+ * contains the translated keyval. It is exported for the benefit of
+ * virtualized test environments.
  *
  * Returns: %TRUE if there was a keyval bound to keycode/state/group.
  */
diff --git a/gdk/gdkgl.c b/gdk/gdkgl.c
index 5ebd2138d8..eb16ec8d17 100644
--- a/gdk/gdkgl.c
+++ b/gdk/gdkgl.c
@@ -301,13 +301,15 @@ gdk_gl_texture_quads (GdkGLContext *paint_context,
  * @width: The width of the region to draw
  * @height: The height of the region to draw
  *
- * This is the main way to draw GL content in GTK. It takes a render buffer ID 
- * (@source_type == #GL_RENDERBUFFER) or a texture id (@source_type == #GL_TEXTURE)
- * and draws it onto @cr with an OVER operation, respecting the current clip.
- * The top left corner of the rectangle specified by @x, @y, @width and @height
- * will be drawn at the current (0,0) position of the cairo_t.
+ * The main way to draw GL content in GTK.
  *
- * This will work for *all* cairo_t, as long as @surface is realized, but the
+ * It takes a render buffer ID (@source_type == #GL_RENDERBUFFER) or a texture
+ * id (@source_type == #GL_TEXTURE) and draws it onto @cr with an OVER operation,
+ * respecting the current clip. The top left corner of the rectangle specified
+ * by @x, @y, @width and @height will be drawn at the current (0,0) position of
+ * the `cairo_t`.
+ *
+ * This will work for *all* `cairo_t`, as long as @surface is realized, but the
  * fallback implementation that reads back the pixels from the buffer may be
  * used in the general case. In the case of direct drawing to a surface with
  * no special effects applied to @cr it will however use a more efficient
diff --git a/gdk/gdkkeys.c b/gdk/gdkkeys.c
index f25647f74f..90f42c5472 100644
--- a/gdk/gdkkeys.c
+++ b/gdk/gdkkeys.c
@@ -135,8 +135,9 @@ gdk_keymap_class_init (GdkKeymapClass *klass)
    * GdkKeymap::direction-changed:
    * @keymap: the object on which the signal is emitted
    *
-   * The ::direction-changed signal gets emitted when the direction
-   * of the keymap changes. See gdk_keymap_get_direction().
+   * Emitted when the direction of the keymap changes.
+   *
+   * See gdk_keymap_get_direction().
    */
   signals[DIRECTION_CHANGED] =
     g_signal_new (g_intern_static_string ("direction-changed"),
@@ -147,6 +148,7 @@ gdk_keymap_class_init (GdkKeymapClass *klass)
                  NULL,
                  G_TYPE_NONE,
                  0);
+
   /**
    * GdkKeymap::keys-changed:
    * @keymap: the object on which the signal is emitted
@@ -305,6 +307,7 @@ gdk_keyval_is_lower (guint keyval)
  * @keymap: a #GdkKeymap
  *
  * Returns the direction of effective layout of the keymap.
+ *
  * The direction of a layout is the direction of the majority of its
  * symbols. See pango_unichar_direction().
  *
@@ -678,6 +681,7 @@ gdk_keyval_from_name (const char *keyval_name)
  * @upper: (out): return location for uppercase version of @symbol
  *
  * Obtains the upper- and lower-case versions of the keyval @symbol.
+ *
  * Examples of keyvals are #GDK_KEY_a, #GDK_KEY_Enter, #GDK_KEY_F1, etc.
  */
 void
diff --git a/gdk/gdkkeyuni.c b/gdk/gdkkeyuni.c
index 77261de6bf..e19167f9ad 100644
--- a/gdk/gdkkeyuni.c
+++ b/gdk/gdkkeyuni.c
@@ -880,7 +880,7 @@ static const struct {
  * gdk_keyval_to_unicode:
  * @keyval: a GDK key symbol
  *
- * Convert from a GDK key symbol to the corresponding ISO10646 (Unicode)
+ * Convert from a GDK key symbol to the corresponding Unicode
  * character.
  *
  * Note that the conversion does not take the current locale
@@ -888,8 +888,8 @@ static const struct {
  * keyvals, such as %GDK_KEY_KP_Decimal.
  *
  * Returns: the corresponding unicode character, or 0 if there
- *               is no corresponding character.
- **/
+ *   is no corresponding character.
+ */
 guint32
 gdk_keyval_to_unicode (guint keyval)
 {
@@ -1682,14 +1682,13 @@ static const struct {
 
 /**
  * gdk_unicode_to_keyval:
- * @wc: a ISO10646 encoded character
- * 
- * Convert from a ISO10646 character to a key symbol.
- * 
+ * @wc: a Unicode character
+ *
+ * Convert from a Unicode character to a key symbol.
+ *
  * Returns: the corresponding GDK key symbol, if one exists.
- *               or, if there is no corresponding symbol, 
- *               wc | 0x01000000
- **/
+ *   or, if there is no corresponding symbol, wc | 0x01000000
+ */
 guint
 gdk_unicode_to_keyval (guint32 wc)
 {
diff --git a/gdk/gdkpango.c b/gdk/gdkpango.c
index 5c25b3521b..759296511f 100644
--- a/gdk/gdkpango.c
+++ b/gdk/gdkpango.c
@@ -90,31 +90,32 @@ layout_iter_get_line_clip_region (PangoLayoutIter *iter,
 
 /**
  * gdk_pango_layout_line_get_clip_region: (skip)
- * @line: a #PangoLayoutLine 
+ * @line: a `PangoLayoutLine`
  * @x_origin: X pixel where you intend to draw the layout line with this clip
  * @y_origin: baseline pixel where you intend to draw the layout line with this clip
  * @index_ranges: (array): array of byte indexes into the layout,
  *     where even members of array are start indexes and odd elements
  *     are end indexes
  * @n_ranges: number of ranges in @index_ranges, i.e. half the size of @index_ranges
- * 
+ *
  * Obtains a clip region which contains the areas where the given
- * ranges of text would be drawn. @x_origin and @y_origin are the top left
- * position of the layout. @index_ranges
- * should contain ranges of bytes in the layout’s text. The clip
- * region will include space to the left or right of the line (to the
- * layout bounding box) if you have indexes above or below the indexes
- * contained inside the line. This is to draw the selection all the way
- * to the side of the layout. However, the clip region is in line coordinates,
- * not layout coordinates.
+ * ranges of text would be drawn.
+ *
+ * @x_origin and @y_origin are the top left position of the layout.
+ * @index_ranges should contain ranges of bytes in the layout’s text.
+ * The clip region will include space to the left or right of the line
+ * (to the layout bounding box) if you have indexes above or below the
+ * indexes contained inside the line. This is to draw the selection all
+ * the way to the side of the layout. However, the clip region is in line
+ * coordinates, not layout coordinates.
  *
  * Note that the regions returned correspond to logical extents of the text
  * ranges, not ink extents. So the drawn line may in fact touch areas out of
  * the clip region.  The clip region is mainly useful for highlightling parts
  * of text, such as when text is selected.
- * 
+ *
  * Returns: a clip region containing the given ranges
- **/
+ */
 cairo_region_t*
 gdk_pango_layout_line_get_clip_region (PangoLayoutLine *line,
                                        int              x_origin,
@@ -141,24 +142,25 @@ gdk_pango_layout_line_get_clip_region (PangoLayoutLine *line,
 
 /**
  * gdk_pango_layout_get_clip_region: (skip)
- * @layout: a #PangoLayout 
+ * @layout: a `PangoLayout`
  * @x_origin: X pixel where you intend to draw the layout with this clip
  * @y_origin: Y pixel where you intend to draw the layout with this clip
  * @index_ranges: array of byte indexes into the layout, where even members of array are start indexes and 
odd elements are end indexes
  * @n_ranges: number of ranges in @index_ranges, i.e. half the size of @index_ranges
- * 
+ *
  * Obtains a clip region which contains the areas where the given ranges
- * of text would be drawn. @x_origin and @y_origin are the top left point
- * to center the layout. @index_ranges should contain
- * ranges of bytes in the layout’s text.
- * 
+ * of text would be drawn.
+ *
+ * @x_origin and @y_origin are the top left point to center the layout.
+ * @index_ranges should contain ranges of bytes in the layout’s text.
+ *
  * Note that the regions returned correspond to logical extents of the text
  * ranges, not ink extents. So the drawn layout may in fact touch areas out of
  * the clip region.  The clip region is mainly useful for highlightling parts
  * of text, such as when text is selected.
- * 
+ *
  * Returns: a clip region containing the given ranges
- **/
+ */
 cairo_region_t*
 gdk_pango_layout_get_clip_region (PangoLayout *layout,
                                   int          x_origin,
diff --git a/gdk/gdkpixbuf-drawable.c b/gdk/gdkpixbuf-drawable.c
index b0d113cfaf..f3636226d1 100644
--- a/gdk/gdkpixbuf-drawable.c
+++ b/gdk/gdkpixbuf-drawable.c
@@ -30,17 +30,6 @@
 
 #include <gdk-pixbuf/gdk-pixbuf.h>
 
-/**
- * SECTION:pixbufs
- * @Short_description: Functions for obtaining pixbufs
- * @Title: GdkPixbuf Interaction
- *
- * Pixbufs are client-side images. For details on how to create
- * and manipulate pixbufs, see the #GdkPixbuf API documentation.
- *
- * The functions described here allow to obtain pixbufs from
- * #GdkSurfaces and cairo surfaces.
- */
 
 static cairo_format_t
 gdk_cairo_format_for_content (cairo_content_t content)
@@ -157,9 +146,10 @@ convert_no_alpha (guchar *dest_data,
  * @width: Width in pixels of region to get
  * @height: Height in pixels of region to get
  *
- * Transfers image data from a #cairo_surface_t and converts it to an RGB(A)
- * representation inside a #GdkPixbuf. This allows you to efficiently read
- * individual pixels from cairo surfaces.
+ * Transfers image data from a `cairo_surface_t` and converts it
+ * to a `GdkPixbuf`.
+ *
+ * This allows you to efficiently read individual pixels from cairo surfaces.
  *
  * This function will create an RGB pixbuf with 8 bits per channel.
  * The pixbuf will contain an alpha channel if the @surface contains one.
@@ -227,11 +217,13 @@ gdk_pixbuf_get_from_surface  (cairo_surface_t *surface,
 
 /**
  * gdk_pixbuf_get_from_texture:
- * @texture: a #GdkTexture
+ * @texture: a `GdkTexture`
+ *
+ * Creates a new pixbuf from @texture.
  *
- * Creates a new pixbuf from @texture. This should generally not be used
- * in newly written code as later stages will almost certainly convert
- * the pixbuf back into a texture to draw it on screen.
+ * This should generally not be used in newly written code as later
+ * 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
diff --git a/gdk/gdktypes.h b/gdk/gdktypes.h
index 1c72061a61..14f1107da4 100644
--- a/gdk/gdktypes.h
+++ b/gdk/gdktypes.h
@@ -148,9 +148,11 @@ typedef enum
  * @GDK_HYPER_MASK: the Hyper modifier
  * @GDK_META_MASK: the Meta modifier
  *
- * A set of bit-flags to indicate the state of modifier keys and mouse buttons
- * in various event types. Typical modifier keys are Shift, Control, Meta,
- * Super, Hyper, Alt, Compose, Apple, CapsLock or ShiftLock.
+ * Flags to indicate the state of modifier keys and mouse buttons
+ * in events.
+ *
+ * Typical modifier keys are Shift, Control, Meta, Super, Hyper, Alt, Compose,
+ * Apple, CapsLock or ShiftLock.
  *
  * Note that GDK may add internal values to events which include values outside
  * of this enumeration. Your code should preserve and ignore them.  You can use
@@ -178,7 +180,7 @@ typedef enum
 /**
  * GDK_MODIFIER_MASK:
  *
- * A mask covering all entries in #GdkModifierType.
+ * A mask covering all entries in `GdkModifierType`.
  */
 #define GDK_MODIFIER_MASK (GDK_SHIFT_MASK|GDK_LOCK_MASK|GDK_CONTROL_MASK| \
                            GDK_ALT_MASK|GDK_SUPER_MASK|GDK_HYPER_MASK|GDK_META_MASK| \
@@ -194,7 +196,7 @@ typedef enum
  * @GDK_GL_ERROR_COMPILATION_FAILED: The shader compilation failed
  * @GDK_GL_ERROR_LINK_FAILED: The shader linking failed
  *
- * Error enumeration for #GdkGLContext.
+ * Error enumeration for `GdkGLContext`.
  */
 typedef enum {
   GDK_GL_ERROR_NOT_AVAILABLE,
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]