[gtk/ebassi/gidocgen: 347/481] stylecontext: Convert docs

From: Emmanuele Bassi <ebassi src gnome org>
To: commits-list gnome org
Cc:
Subject: [gtk/ebassi/gidocgen: 347/481] stylecontext: Convert docs
Date: Sun, 7 Mar 2021 23:55:13 +0000 (UTC)

commit b8113968376dfa1e1c876c4c4ce9f0ab1cb755ae
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun Feb 28 13:12:48 2021 -0500

    stylecontext: Convert docs

 gtk/gtkstylecontext.c | 239 ++++++++++++++++++++++++++------------------------
 1 file changed, 122 insertions(+), 117 deletions(-)
---
diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c
index 71f4750252..b95af474d1 100644
--- a/gtk/gtkstylecontext.c
+++ b/gtk/gtkstylecontext.c
@@ -48,46 +48,41 @@
 
 
 /**
- * SECTION:gtkstylecontext
- * @Short_description: Rendering UI elements
- * @Title: GtkStyleContext
+ * GtkStyleContext:
  *
- * #GtkStyleContext is an object that stores styling information affecting
- * a widget.
+ * `GtkStyleContext` stores styling information affecting a widget.
  *
- * In order to construct the final style information, #GtkStyleContext
- * queries information from all attached #GtkStyleProviders. Style providers
- * can be either attached explicitly to the context through
- * gtk_style_context_add_provider(), or to the display through
- * gtk_style_context_add_provider_for_display(). The resulting style is a
- * combination of all providers’ information in priority order.
+ * In order to construct the final style information, `GtkStyleContext`
+ * queries information from all attached `GtkStyleProviders`. Style
+ * providers can be either attached explicitly to the context through
+ * [method@Gtk.StyleContext.add_provider], or to the display through
+ * [func@Gtk.StyleContext.add_provider_for_display]. The resulting
+ * style is a combination of all providers’ information in priority order.
  *
- * For GTK widgets, any #GtkStyleContext returned by
- * gtk_widget_get_style_context() will already have a #GdkDisplay and
- * RTL/LTR information set. The style context will also be updated
+ * For GTK widgets, any `GtkStyleContext` returned by
+ * [method@Gtk.Widget.get_style_context] will already have a `GdkDisplay`
+ * and RTL/LTR information set. The style context will also be updated
  * automatically if any of these settings change on the widget.
  *
- * # Style Classes # {#gtkstylecontext-classes}
+ * # Style Classes
  *
  * Widgets can add style classes to their context, which can be used to associate
  * different styles by class. The documentation for individual widgets lists
  * which style classes it uses itself, and which style classes may be added by
  * applications to affect their appearance.
  *
- * GTK defines macros for a number of style classes.
- *
  * # Custom styling in UI libraries and applications
  *
- * If you are developing a library with custom #GtkWidgets that
- * render differently than standard components, you may need to add a
- * #GtkStyleProvider yourself with the %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK
- * priority, either a #GtkCssProvider or a custom object implementing the
- * #GtkStyleProvider interface. This way themes may still attempt
- * to style your UI elements in a different way if needed so.
+ * If you are developing a library with custom widgets that render differently
+ * than standard components, you may need to add a `GtkStyleProvider` yourself
+ * with the %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK priority, either a
+ * `GtkCssProvider` or a custom object implementing the `GtkStyleProvider`
+ * interface. This way themes may still attempt to style your UI elements in
+ * a different way if needed so.
  *
  * If you are using custom styling on an applications, you probably want then
  * to make your style information prevail to the theme’s, so you must use
- * a #GtkStyleProvider with the %GTK_STYLE_PROVIDER_PRIORITY_APPLICATION
+ * a `GtkStyleProvider` with the %GTK_STYLE_PROVIDER_PRIORITY_APPLICATION
  * priority, keep in mind that the user settings in
  * `XDG_CONFIG_HOME/gtk-4.0/gtk.css` will
  * still take precedence over your changes, as it uses the
@@ -346,24 +341,25 @@ gtk_style_context_new_for_node (GtkCssNode *node)
 
 /**
  * gtk_style_context_add_provider:
- * @context: a #GtkStyleContext
- * @provider: a #GtkStyleProvider
+ * @context: a `GtkStyleContext`
+ * @provider: a `GtkStyleProvider`
  * @priority: the priority of the style provider. The lower
- *            it is, the earlier it will be used in the style
- *            construction. Typically this will be in the range
- *            between %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK and
- *            %GTK_STYLE_PROVIDER_PRIORITY_USER
+ *   it is, the earlier it will be used in the style construction.
+ *   Typically this will be in the range between
+ *   %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK and
+ *   %GTK_STYLE_PROVIDER_PRIORITY_USER
  *
  * Adds a style provider to @context, to be used in style construction.
+ *
  * Note that a style provider added by this function only affects
  * the style of the widget to which @context belongs. If you want
  * to affect the style of all widgets, use
- * gtk_style_context_add_provider_for_display().
+ * [func@Gtk.StyleContext.add_provider_for_display].
  *
- * Note: If both priorities are the same, a #GtkStyleProvider
+ * Note: If both priorities are the same, a `GtkStyleProvider`
  * added through this function takes precedence over another added
- * through gtk_style_context_add_provider_for_display().
- **/
+ * through [func@Gtk.StyleContext.add_provider_for_display].
+ */
 void
 gtk_style_context_add_provider (GtkStyleContext  *context,
                                 GtkStyleProvider *provider,
@@ -394,11 +390,11 @@ gtk_style_context_add_provider (GtkStyleContext  *context,
 
 /**
  * gtk_style_context_remove_provider:
- * @context: a #GtkStyleContext
- * @provider: a #GtkStyleProvider
+ * @context: a `GtkStyleContext`
+ * @provider: a `GtkStyleProvider`
  *
  * Removes @provider from the style providers list in @context.
- **/
+ */
 void
 gtk_style_context_remove_provider (GtkStyleContext  *context,
                                    GtkStyleProvider *provider)
@@ -416,23 +412,23 @@ gtk_style_context_remove_provider (GtkStyleContext  *context,
 
 /**
  * gtk_style_context_add_provider_for_display:
- * @display: a #GdkDisplay
- * @provider: a #GtkStyleProvider
+ * @display: a `GdkDisplay`
+ * @provider: a `GtkStyleProvider`
  * @priority: the priority of the style provider. The lower
- *            it is, the earlier it will be used in the style
- *            construction. Typically this will be in the range
- *            between %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK and
- *            %GTK_STYLE_PROVIDER_PRIORITY_USER
+ *   it is, the earlier it will be used in the style construction.
+ *   Typically this will be in the range between
+ *   %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK and
+ *   %GTK_STYLE_PROVIDER_PRIORITY_USER
  *
  * Adds a global style provider to @display, which will be used
- * in style construction for all #GtkStyleContexts under @display.
+ * in style construction for all `GtkStyleContexts` under @display.
  *
- * GTK uses this to make styling information from #GtkSettings
+ * GTK uses this to make styling information from `GtkSettings`
  * available.
  *
- * Note: If both priorities are the same, A #GtkStyleProvider
- * added through gtk_style_context_add_provider() takes precedence
- * over another added through this function.
+ * Note: If both priorities are the same, A `GtkStyleProvider`
+ * added through [method@Gtk.StyleContext.add_provider] takes
+ * precedence over another added through this function.
  **/
 void
 gtk_style_context_add_provider_for_display (GdkDisplay       *display,
@@ -451,11 +447,11 @@ gtk_style_context_add_provider_for_display (GdkDisplay       *display,
 
 /**
  * gtk_style_context_remove_provider_for_display:
- * @display: a #GdkDisplay
- * @provider: a #GtkStyleProvider
+ * @display: a `GdkDisplay`
+ * @provider: a `GtkStyleProvider`
  *
  * Removes @provider from the global style providers list in @display.
- **/
+ */
 void
 gtk_style_context_remove_provider_for_display (GdkDisplay       *display,
                                                GtkStyleProvider *provider)
@@ -472,11 +468,11 @@ gtk_style_context_remove_provider_for_display (GdkDisplay       *display,
 
 /**
  * gtk_style_context_set_state:
- * @context: a #GtkStyleContext
+ * @context: a `GtkStyleContext`
  * @flags: state to represent
  *
  * Sets the state to be used for style matching.
- **/
+ */
 void
 gtk_style_context_set_state (GtkStyleContext *context,
                              GtkStateFlags    flags)
@@ -490,14 +486,15 @@ gtk_style_context_set_state (GtkStyleContext *context,
 
 /**
  * gtk_style_context_get_state:
- * @context: a #GtkStyleContext
+ * @context: a `GtkStyleContext`
  *
  * Returns the state used for style matching.
  *
- * This method should only be used to retrieve the #GtkStateFlags
- * to pass to #GtkStyleContext methods, like gtk_style_context_get_padding().
- * If you need to retrieve the current state of a #GtkWidget, use
- * gtk_widget_get_state_flags().
+ * This method should only be used to retrieve the `GtkStateFlags`
+ * to pass to `GtkStyleContext` methods, like
+ * [method@Gtk.StyleContext.get_padding].
+ * If you need to retrieve the current state of a `GtkWidget`, use
+ * [method@Gtk.Widget.get_state_flags].
  *
  * Returns: the state flags
  **/
@@ -513,7 +510,7 @@ gtk_style_context_get_state (GtkStyleContext *context)
 
 /**
  * gtk_style_context_set_scale:
- * @context: a #GtkStyleContext
+ * @context: a `GtkStyleContext`
  * @scale: scale
  *
  * Sets the scale to use when getting image assets for the style.
@@ -545,7 +542,7 @@ gtk_style_context_set_scale (GtkStyleContext *context,
 
 /**
  * gtk_style_context_get_scale:
- * @context: a #GtkStyleContext
+ * @context: a `GtkStyleContext`
  *
  * Returns the scale used for assets.
  *
@@ -563,20 +560,23 @@ gtk_style_context_get_scale (GtkStyleContext *context)
 
 /*
  * gtk_style_context_save_to_node:
- * @context: a #GtkStyleContext
+ * @context: a `GtkStyleContext`
  * @node: the node to save to
  *
- * Saves the @context state, so temporary modifications done through
- * gtk_style_context_add_class(), gtk_style_context_remove_class(),
- * gtk_style_context_set_state(), etc. and rendering using
- * gtk_render_background() or similar functions are done using the
- * given @node.
+ * Saves the @context state to a node.
  *
- * To undo, call gtk_style_context_restore().
+ * This allows temporary modifications done through
+ * [method@Gtk.StyleContext.add_class],
+ * [method@Gtk.StyleContext.remove_class],
+ * [method@Gtk.StyleContext.set_state] etc.
  *
- * The matching call to gtk_style_context_restore() must be done
- * before GTK returns to the main loop.
- **/
+ * Rendering using [func@Gtk.render_background] or similar
+ * functions are done using the given @node.
+ *
+ * To undo, call [method@Gtk.StyleContext.restore].
+ * The matching call to [method@Gtk.StyleContext.restore]
+ * must be done before GTK returns to the main loop.
+ */
 void
 gtk_style_context_save_to_node (GtkStyleContext *context,
                                 GtkCssNode      *node)
@@ -592,15 +592,18 @@ gtk_style_context_save_to_node (GtkStyleContext *context,
 
 /**
  * gtk_style_context_save:
- * @context: a #GtkStyleContext
+ * @context: a `GtkStyleContext`
+ *
+ * Saves the @context state.
  *
- * Saves the @context state, so temporary modifications done through
- * gtk_style_context_add_class(), gtk_style_context_remove_class(),
- * gtk_style_context_set_state(), etc. can quickly be reverted
- * in one go through gtk_style_context_restore().
+ * This allows temporary modifications done through
+ * [method@Gtk.StyleContext.add_class],
+ * [method@Gtk.StyleContext.remove_class],
+ * [method@Gtk.StyleContext.set_state] to be quickly
+ * reverted in one go through [method@Gtk.StyleContext.restore].
  *
- * The matching call to gtk_style_context_restore() must be done
- * before GTK returns to the main loop.
+ * The matching call to [method@Gtk.StyleContext.restore]
+ * must be done before GTK returns to the main loop.
  **/
 void
 gtk_style_context_save (GtkStyleContext *context)
@@ -626,10 +629,11 @@ gtk_style_context_save (GtkStyleContext *context)
 
 /**
  * gtk_style_context_restore:
- * @context: a #GtkStyleContext
+ * @context: a `GtkStyleContext`
  *
  * Restores @context state to a previous stage.
- * See gtk_style_context_save().
+ *
+ * See [method Gtk StyleContext save].
  **/
 void
 gtk_style_context_restore (GtkStyleContext *context)
@@ -649,25 +653,25 @@ gtk_style_context_restore (GtkStyleContext *context)
 
 /**
  * gtk_style_context_add_class:
- * @context: a #GtkStyleContext
+ * @context: a `GtkStyleContext`
  * @class_name: class name to use in styling
  *
  * Adds a style class to @context, so later uses of the
  * style context will make use of this new class for styling.
  *
- * In the CSS file format, a #GtkEntry defining a “search”
+ * In the CSS file format, a `GtkEntry` defining a “search”
  * class, would be matched by:
  *
- * |[ <!-- language="CSS" -->
+ * ```css
  * entry.search { ... }
- * ]|
+ * ```
  *
  * While any widget defining a “search” class would be
  * matched by:
- * |[ <!-- language="CSS" -->
+ * ```css
  * .search { ... }
- * ]|
- **/
+ * ```
+ */
 void
 gtk_style_context_add_class (GtkStyleContext *context,
                              const char      *class_name)
@@ -685,11 +689,11 @@ gtk_style_context_add_class (GtkStyleContext *context,
 
 /**
  * gtk_style_context_remove_class:
- * @context: a #GtkStyleContext
+ * @context: a `GtkStyleContext`
  * @class_name: class name to remove
  *
  * Removes @class_name from @context.
- **/
+ */
 void
 gtk_style_context_remove_class (GtkStyleContext *context,
                                 const char      *class_name)
@@ -709,7 +713,7 @@ gtk_style_context_remove_class (GtkStyleContext *context,
 
 /**
  * gtk_style_context_has_class:
- * @context: a #GtkStyleContext
+ * @context: a `GtkStyleContext`
  * @class_name: a class name
  *
  * Returns %TRUE if @context currently has defined the
@@ -745,18 +749,18 @@ _gtk_style_context_peek_property (GtkStyleContext *context,
 
 /**
  * gtk_style_context_set_display:
- * @context: a #GtkStyleContext
- * @display: a #GdkDisplay
+ * @context: a `GtkStyleContext`
+ * @display: a `GdkDisplay`
  *
  * Attaches @context to the given display.
  *
- * The display is used to add style information from “global” style
- * providers, such as the display's #GtkSettings instance.
+ * The display is used to add style information from “global”
+ * style providers, such as the display's `GtkSettings` instance.
  *
- * If you are using a #GtkStyleContext returned from
- * gtk_widget_get_style_context(), you do not need to
+ * If you are using a `GtkStyleContext` returned from
+ * [method@Gtk.Widget.get_style_context], you do not need to
  * call this yourself.
- **/
+ */
 void
 gtk_style_context_set_display (GtkStyleContext *context,
                                GdkDisplay      *display)
@@ -789,12 +793,12 @@ gtk_style_context_set_display (GtkStyleContext *context,
 
 /**
  * gtk_style_context_get_display:
- * @context: a #GtkStyleContext
+ * @context: a `GtkStyleContext`
  *
- * Returns the #GdkDisplay to which @context is attached.
+ * Returns the `GdkDisplay` to which @context is attached.
  *
- * Returns: (transfer none): a #GdkDisplay.
- **/
+ * Returns: (transfer none): a `GdkDisplay`.
+ */
 GdkDisplay *
 gtk_style_context_get_display (GtkStyleContext *context)
 {
@@ -831,14 +835,14 @@ gtk_style_context_resolve_color (GtkStyleContext    *context,
 
 /**
  * gtk_style_context_lookup_color:
- * @context: a #GtkStyleContext
+ * @context: a `GtkStyleContext`
  * @color_name: color name to lookup
  * @color: (out): Return location for the looked up color
  *
  * Looks up and resolves a color name in the @context color map.
  *
  * Returns: %TRUE if @color_name was found and resolved, %FALSE otherwise
- **/
+ */
 gboolean
 gtk_style_context_lookup_color (GtkStyleContext *context,
                                 const char      *color_name,
@@ -860,11 +864,11 @@ gtk_style_context_lookup_color (GtkStyleContext *context,
 
 /**
  * gtk_style_context_get_color:
- * @context: a #GtkStyleContext
+ * @context: a `GtkStyleContext`
  * @color: (out): return value for the foreground color
  *
  * Gets the foreground color for a given state.
- **/
+ */
 void
 gtk_style_context_get_color (GtkStyleContext *context,
                              GdkRGBA         *color)
@@ -877,11 +881,11 @@ gtk_style_context_get_color (GtkStyleContext *context,
 
 /**
  * gtk_style_context_get_border:
- * @context: a #GtkStyleContext
+ * @context: a `GtkStyleContext`
  * @border: (out): return value for the border settings
  *
- * Gets the border for a given state as a #GtkBorder.
- **/
+ * Gets the border for a given state as a `GtkBorder`.
+ */
 void
 gtk_style_context_get_border (GtkStyleContext *context,
                               GtkBorder       *border)
@@ -901,11 +905,11 @@ gtk_style_context_get_border (GtkStyleContext *context,
 
 /**
  * gtk_style_context_get_padding:
- * @context: a #GtkStyleContext
+ * @context: a `GtkStyleContext`
  * @padding: (out): return value for the padding settings
  *
- * Gets the padding for a given state as a #GtkBorder.
- **/
+ * Gets the padding for a given state as a `GtkBorder`.
+ */
 void
 gtk_style_context_get_padding (GtkStyleContext *context,
                                GtkBorder       *padding)
@@ -925,11 +929,11 @@ gtk_style_context_get_padding (GtkStyleContext *context,
 
 /**
  * gtk_style_context_get_margin:
- * @context: a #GtkStyleContext
+ * @context: a `GtkStyleContext`
  * @margin: (out): return value for the margin settings
  *
- * Gets the margin for a given state as a #GtkBorder.
- **/
+ * Gets the margin for a given state as a `GtkBorder`.
+ */
 void
 gtk_style_context_get_margin (GtkStyleContext *context,
                               GtkBorder       *margin)
@@ -1116,15 +1120,15 @@ snapshot_insertion_cursor (GtkSnapshot     *snapshot,
 /**
  * gtk_snapshot_render_insertion_cursor:
  * @snapshot: snapshot to render to
- * @context: a #GtkStyleContext
+ * @context: a `GtkStyleContext`
  * @x: X origin
  * @y: Y origin
- * @layout: the #PangoLayout of the text
+ * @layout: the `PangoLayout` of the text
  * @index: the index in the #PangoLayout
  * @direction: the #PangoDirection of the text
  *
  * Draws a text caret using @snapshot at the specified index of @layout.
- **/
+ */
 void
 gtk_snapshot_render_insertion_cursor (GtkSnapshot     *snapshot,
                                       GtkStyleContext *context,
@@ -1222,12 +1226,13 @@ gtk_snapshot_render_insertion_cursor (GtkSnapshot     *snapshot,
  *     what changes affect the styles
  *
  * Flags that modify the behavior of gtk_style_context_to_string().
+ *
  * New values may be added to this enumeration.
  */
 
 /**
  * gtk_style_context_to_string:
- * @context: a #GtkStyleContext
+ * @context: a `GtkStyleContext`
  * @flags: Flags that determine what to print
  *
  * Converts the style context into a string representation.
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]