From c30d09cef45174aa71cca5bad707cca34be43669 Mon Sep 17 00:00:00 2001 From: Maximiliano Sandoval R Date: Wed, 5 Jan 2022 12:24:06 +0100 Subject: [PATCH 1/5] docs: Improve docs for gtkactionable.c --- gtk/gtkactionable.c | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/gtk/gtkactionable.c b/gtk/gtkactionable.c index 69581d2f1d..a37792ab4c 100644 --- a/gtk/gtkactionable.c +++ b/gtk/gtkactionable.c @@ -44,10 +44,10 @@ /** * GtkActionableInterface: - * @get_action_name: virtual function for gtk_actionable_get_action_name() - * @set_action_name: virtual function for gtk_actionable_set_action_name() - * @get_action_target_value: virtual function for gtk_actionable_get_action_target_value() - * @set_action_target_value: virtual function for gtk_actionable_set_action_target_value() + * @get_action_name: virtual function for [method@Actionable.get_action_name] + * @set_action_name: virtual function for [method@Actionable.set_action_name] + * @get_action_target_value: virtual function for [method@Actionable.get_action_target_value] + * @set_action_target_value: virtual function for [method@Actionable.set_action_target_value] * * The interface vtable for `GtkActionable`. **/ @@ -100,8 +100,8 @@ gtk_actionable_get_action_name (GtkActionable *actionable) * located) within the hierarchy of a `GtkApplicationWindow`. * * Names are of the form “win.save” or “app.quit” for actions on the - * containing `GtkApplicationWindow` or its associated `GtkApplication`, - * respectively. This is the same form used for actions in the `GMenu` + * containing [class@ApplicationWindow] or its associated [class@Application], + * respectively. This is the same form used for actions in the [class@Gio.Menu] * associated with the window. */ void @@ -134,7 +134,7 @@ gtk_actionable_get_action_target_value (GtkActionable *actionable) /** * gtk_actionable_set_action_target_value: (attributes org.gtk.Method.set_property=action-target) * @actionable: a `GtkActionable` widget - * @target_value: (nullable): a `GVariant` to set as the target value + * @target_value: (nullable): a [struct@GLib.Variant] to set as the target value * * Sets the target value of an actionable widget. * @@ -145,7 +145,7 @@ gtk_actionable_get_action_target_value (GtkActionable *actionable) * Second, it is used to determine if the widget should be rendered as * “active” — the widget is active if the state is equal to the given target. * - * Consider the example of associating a set of buttons with a `GAction` + * Consider the example of associating a set of buttons with a [iface@Gio.Action] * with string state in a typical “radio button” situation. Each button * will be associated with the same action, but with a different target * value for that action. Clicking on a particular button will activate @@ -168,12 +168,12 @@ gtk_actionable_set_action_target_value (GtkActionable *actionable, /** * gtk_actionable_set_action_target: * @actionable: a `GtkActionable` widget - * @format_string: a GVariant format string + * @format_string: a [struct@GLib.Variant] format string * @...: arguments appropriate for @format_string * * Sets the target of an actionable widget. * - * This is a convenience function that calls g_variant_new() for + * This is a convenience function that calls [ctor@GLib.Variant.new] for * @format_string and uses the result to call * [method@Gtk.Actionable.set_action_target_value]. * @@ -202,7 +202,7 @@ gtk_actionable_set_action_target (GtkActionable *actionable, * actionable widget. * * @detailed_action_name is a string in the format accepted by - * g_action_parse_detailed_name(). + * [func@Gio.Action.parse_detailed_name]. */ void gtk_actionable_set_detailed_action_name (GtkActionable *actionable, From c36a10da8347bab70be66126e7eea72eae6fe131 Mon Sep 17 00:00:00 2001 From: Maximiliano Sandoval R Date: Wed, 5 Jan 2022 12:24:41 +0100 Subject: [PATCH 2/5] docs: Improve docs for gtkversion.h --- gtk/gtkversion.h.in | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/gtk/gtkversion.h.in b/gtk/gtkversion.h.in index a8d3729d23..992863dd7a 100644 --- a/gtk/gtkversion.h.in +++ b/gtk/gtkversion.h.in @@ -36,7 +36,7 @@ G_BEGIN_DECLS /** * GTK_MAJOR_VERSION: * - * Like gtk_get_major_version(), but from the headers used at + * Like [func@get_major_version], but from the headers used at * application compile time, rather than from the library linked * against at application run time. */ @@ -45,7 +45,7 @@ G_BEGIN_DECLS /** * GTK_MINOR_VERSION: * - * Like gtk_get_minor_version(), but from the headers used at + * Like [func@get_minor_version], but from the headers used at * application compile time, rather than from the library linked * against at application run time. */ @@ -54,7 +54,7 @@ G_BEGIN_DECLS /** * GTK_MICRO_VERSION: * - * Like gtk_get_micro_version(), but from the headers used at + * Like [func@get_micro_version], but from the headers used at * application compile time, rather than from the library linked * against at application run time. */ @@ -63,7 +63,7 @@ G_BEGIN_DECLS /** * GTK_BINARY_AGE: * - * Like gtk_get_binary_age(), but from the headers used at + * Like [func@get_binary_age], but from the headers used at * application compile time, rather than from the library linked * against at application run time. */ @@ -72,7 +72,7 @@ G_BEGIN_DECLS /** * GTK_INTERFACE_AGE: * - * Like gtk_get_interface_age(), but from the headers used at + * Like [func@get_interface_age], but from the headers used at * application compile time, rather than from the library linked * against at application run time. */ From 6d80135342692c6a26ff964a89ead01a2bfdd32f Mon Sep 17 00:00:00 2001 From: Maximiliano Sandoval R Date: Wed, 5 Jan 2022 12:36:55 +0100 Subject: [PATCH 3/5] docs: Improve docs for gtksnapshot.c --- gtk/gtksnapshot.c | 63 ++++++++++++++++++++++------------------------- 1 file changed, 29 insertions(+), 34 deletions(-) diff --git a/gtk/gtksnapshot.c b/gtk/gtksnapshot.c index 1b917ce384..0c05ecad0e 100644 --- a/gtk/gtksnapshot.c +++ b/gtk/gtksnapshot.c @@ -46,14 +46,14 @@ /** * GtkSnapshot: * - * `GtkSnapshot` assists in creating `GskRenderNodes` for widgets. + * `GtkSnapshot` assists in creating [class@Gsk.RenderNode]s for widgets. * * It functions in a similar way to a cairo context, and maintains a stack * of render nodes and their associated transformations. * - * The node at the top of the stack is the one that gtk_snapshot_append_… - * functions operate on. Use the gtk_snapshot_push_… functions and - * gtk_snapshot_pop() to change the current node. + * The node at the top of the stack is the one that `gtk_snapshot_append_…()` + * functions operate on. Use the `gtk_snapshot_push_…()` functions and + * [method@Snapshot.pop] to change the current node. * * The typical way to obtain a `GtkSnapshot` object is as an argument to * the [vfunc@Gtk.Widget.snapshot] vfunc. If you need to create your own @@ -302,7 +302,7 @@ gtk_snapshot_new (void) * Returns the node that was constructed by @snapshot * and frees @snapshot. * - * Returns: (transfer full): a newly-created `GskRenderNode` + * Returns: (transfer full): a newly-created [class@Gsk.RenderNode] */ GskRenderNode * gtk_snapshot_free_to_node (GtkSnapshot *snapshot) @@ -324,7 +324,7 @@ gtk_snapshot_free_to_node (GtkSnapshot *snapshot) * Returns a paintable for the node that was * constructed by @snapshot and frees @snapshot. * - * Returns: (transfer full): a newly-created `GdkPaintable` + * Returns: (transfer full): a newly-created [iface@Gdk.Paintable] */ GdkPaintable * gtk_snapshot_free_to_paintable (GtkSnapshot *snapshot, @@ -955,11 +955,11 @@ gtk_snapshot_collect_gl_shader_texture (GtkSnapshot *snapshot, * @bounds: the rectangle to render into * @take_args: (transfer full): Data block with arguments for the shader. * - * Push a `GskGLShaderNode`. + * Push a [class@Gsk.GLShaderNode]. * * The node uses the given [class@Gsk.GLShader] and uniform values * Additionally this takes a list of @n_children other nodes - * which will be passed to the `GskGLShaderNode`. + * which will be passed to the [class@Gsk.GLShaderNode]. * * The @take_args argument is a block of data to use for uniform * arguments, as per types and offsets defined by the @shader. @@ -1495,7 +1495,7 @@ gtk_snapshot_pop_collect (GtkSnapshot *snapshot) * * After calling this function, it is no longer possible to * add more nodes to @snapshot. The only function that should - * be called after this is g_object_unref(). + * be called after this is [method@GObject.Object.unref]. * * Returns: (transfer full): the constructed `GskRenderNode` */ @@ -1530,7 +1530,7 @@ gtk_snapshot_to_node (GtkSnapshot *snapshot) * * After calling this function, it is no longer possible to * add more nodes to @snapshot. The only function that should - * be called after this is g_object_unref(). + * be called after this is [method@GObject.Object.unref]. * * Returns: (transfer full): a new `GdkPaintable` */ @@ -1585,7 +1585,7 @@ gtk_snapshot_pop (GtkSnapshot *snapshot) * @snapshot: a `GtkSnapshot` * * Removes the top element from the stack of render nodes and - * adds it to the nearest `GskGLShaderNode` below it. + * adds it to the nearest [class@Gsk.GLShaderNode] below it. * * This must be called the same number of times as the number * of textures is needed for the shader in @@ -1610,12 +1610,12 @@ gtk_snapshot_gl_shader_pop_texture (GtkSnapshot *snapshot) * * When [method@Gtk.Snapshot.restore] is called, @snapshot will * be restored to the saved state. Multiple calls to - * gtk_snapshot_save() and gtk_snapshot_restore() can be nested; - * each call to gtk_snapshot_restore() restores the state from - * the matching paired gtk_snapshot_save(). + * [method@Snapshot.save] and [class@Snapshot.restore] can be nested; + * each call to `gtk_snapshot_restore()` restores the state from + * the matching paired `gtk_snapshot_save()`. * * It is necessary to clear all saved states with corresponding - * calls to gtk_snapshot_restore(). + * calls to `gtk_snapshot_restore()`. */ void gtk_snapshot_save (GtkSnapshot *snapshot) @@ -1633,7 +1633,7 @@ gtk_snapshot_save (GtkSnapshot *snapshot) * @snapshot: a `GtkSnapshot` * * Restores @snapshot to the state saved by a preceding call to - * gtk_snapshot_save() and removes that state from the stack of + * [method@Snapshot.save] and removes that state from the stack of * saved states. */ void @@ -1882,7 +1882,7 @@ gtk_snapshot_append_node (GtkSnapshot *snapshot, * @snapshot: a `GtkSnapshot` * @bounds: the bounds for the new node * - * Creates a new `GskCairoNode` and appends it to the current + * Creates a new [class@Gsk.CairoNode] and appends it to the current * render node of @snapshot, without changing the current node. * * Returns: a `cairo_t` suitable for drawing the contents of @@ -1918,7 +1918,7 @@ gtk_snapshot_append_cairo (GtkSnapshot *snapshot, /** * gtk_snapshot_append_texture: * @snapshot: a `GtkSnapshot` - * @texture: the `GdkTexture` to render + * @texture: the texture to render * @bounds: the bounds for the new node * * Creates a new render node drawing the @texture @@ -1948,7 +1948,7 @@ gtk_snapshot_append_texture (GtkSnapshot *snapshot, /** * gtk_snapshot_append_color: * @snapshot: a `GtkSnapshot` - * @color: the `GdkRGBA` to draw + * @color: the color to draw * @bounds: the bounds for the new node * * Creates a new render node drawing the @color into the @@ -1982,7 +1982,7 @@ gtk_snapshot_append_color (GtkSnapshot *snapshot, /** * gtk_snapshot_render_background: * @snapshot: a `GtkSnapshot` - * @context: the `GtkStyleContext` to use + * @context: the style context that defines the background * @x: X origin of the rectangle * @y: Y origin of the rectangle * @width: rectangle width @@ -2014,7 +2014,7 @@ gtk_snapshot_render_background (GtkSnapshot *snapshot, /** * gtk_snapshot_render_frame: * @snapshot: a `GtkSnapshot` - * @context: the `GtkStyleContext` to use + * @context: the style context that defines the frame * @x: X origin of the rectangle * @y: Y origin of the rectangle * @width: rectangle width @@ -2046,7 +2046,7 @@ gtk_snapshot_render_frame (GtkSnapshot *snapshot, /** * gtk_snapshot_render_focus: * @snapshot: a `GtkSnapshot` - * @context: the `GtkStyleContext` to use + * @context: the style context that defines the focus ring * @x: X origin of the rectangle * @y: Y origin of the rectangle * @width: rectangle width @@ -2078,7 +2078,7 @@ gtk_snapshot_render_focus (GtkSnapshot *snapshot, /** * gtk_snapshot_render_layout: * @snapshot: a `GtkSnapshot` - * @context: the `GtkStyleContext` to use + * @context: the style context that defines the text * @x: X origin of the rectangle * @y: Y origin of the rectangle * @layout: the `PangoLayout` to render @@ -2152,8 +2152,7 @@ gtk_snapshot_append_text (GtkSnapshot *snapshot, * @bounds: the rectangle to render the linear gradient into * @start_point: the point at which the linear gradient will begin * @end_point: the point at which the linear gradient will finish - * @stops: (array length=n_stops): a pointer to an array of `GskColorStop` - * defining the gradient + * @stops: (array length=n_stops): the color stops defining the gradient * @n_stops: the number of elements in @stops * * Appends a linear gradient node with the given stops to @snapshot. @@ -2220,8 +2219,7 @@ gtk_snapshot_append_linear_gradient (GtkSnapshot *snapshot, * @bounds: the rectangle to render the linear gradient into * @start_point: the point at which the linear gradient will begin * @end_point: the point at which the linear gradient will finish - * @stops: (array length=n_stops): a pointer to an array of `GskColorStop` - * defining the gradient + * @stops: (array length=n_stops): the color stops defining the gradient * @n_stops: the number of elements in @stops * * Appends a repeating linear gradient node with the given stops to @snapshot. @@ -2289,8 +2287,7 @@ gtk_snapshot_append_repeating_linear_gradient (GtkSnapshot *snapshot, * @center: the center point of the conic gradient * @rotation: the clockwise rotation in degrees of the starting angle. * 0 means the starting angle is the top. - * @stops: (array length=n_stops): a pointer to an array of `GskColorStop` - * defining the gradient + * @stops: (array length=n_stops): the color stops defining the gradient * @n_stops: the number of elements in @stops * * Appends a conic gradient node with the given stops to @snapshot. @@ -2352,8 +2349,7 @@ gtk_snapshot_append_conic_gradient (GtkSnapshot *snapshot, * @vradius: the vertical radius * @start: the start position (on the horizontal axis) * @end: the end position (on the horizontal axis) - * @stops: (array length=n_stops): a pointer to an array of `GskColorStop` - * defining the gradient + * @stops: (array length=n_stops): the color stops defining the gradient * @n_stops: the number of elements in @stops * * Appends a radial gradient node with the given stops to @snapshot. @@ -2426,8 +2422,7 @@ gtk_snapshot_append_radial_gradient (GtkSnapshot *snapshot, * @vradius: the vertical radius * @start: the start position (on the horizontal axis) * @end: the end position (on the horizontal axis) - * @stops: (array length=n_stops): a pointer to an array of `GskColorStop` - * defining the gradient + * @stops: (array length=n_stops): the color stops defining the gradient * @n_stops: the number of elements in @stops * * Appends a repeating radial gradient node with the given stops to @snapshot. @@ -2493,7 +2488,7 @@ gtk_snapshot_append_repeating_radial_gradient (GtkSnapshot *snapshot, /** * gtk_snapshot_append_border: * @snapshot: a `GtkSnapshot` - * @outline: a `GskRoundedRect` describing the outline of the border + * @outline: the outline of the border * @border_width: (array fixed-size=4): the stroke width of the border on * the top, right, bottom and left side respectively. * @border_color: (array fixed-size=4): the color used on the top, right, From ad73e2d07ba347c3e3868520f705c7ded97903d4 Mon Sep 17 00:00:00 2001 From: Maximiliano Sandoval R Date: Wed, 5 Jan 2022 12:43:06 +0100 Subject: [PATCH 4/5] docs: Improve docs for gskrendernode.c --- gsk/gskrendernode.c | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/gsk/gskrendernode.c b/gsk/gskrendernode.c index ab15da7a99..295ddf698e 100644 --- a/gsk/gskrendernode.c +++ b/gsk/gskrendernode.c @@ -20,7 +20,7 @@ * GskRenderNode: (ref-func gsk_render_node_ref) (unref-func gsk_render_node_unref) (set-value-func gsk_value_set_render_node) (get-value-func gsk_value_get_render_node) * * `GskRenderNode` is the basic block in a scene graph to be - * rendered using `GskRenderer`. + * rendered using [class@Gsk.Renderer]. * * Each node has a parent, except the top-level node; each node may have * children nodes. @@ -424,7 +424,7 @@ gsk_render_node_get_bounds (GskRenderNode *node, * * Typically, you'll use this function to implement fallback rendering * of `GskRenderNode`s on an intermediate Cairo context, instead of using - * the drawing context associated to a `GdkSurface`'s rendering buffer. + * the drawing context associated to a [class@Gdk.Surface]'s rendering buffer. * * For advanced nodes that cannot be supported using Cairo, in particular * for nodes doing 3D operations, this function may fail. @@ -565,8 +565,8 @@ gsk_render_node_diff (GskRenderNode *node1, * @filename: (type filename): the file to save it to. * @error: Return location for a potential error * - * This function is equivalent to calling gsk_render_node_serialize() - * followed by g_file_set_contents(). + * This function is equivalent to calling [method@Gsk.RenderNode.serialize] + * followed by [func@GLib.file_set_contents]. * * See those two functions for details on the arguments. * @@ -603,7 +603,7 @@ gsk_render_node_write_to_file (GskRenderNode *node, * @error_func: (nullable) (scope call): Callback on parsing errors * @user_data: (closure error_func): user_data for @error_func * - * Loads data previously created via gsk_render_node_serialize(). + * Loads data previously created via [method@Gsk.RenderNode.serialize]. * * For a discussion of the supported format, see that function. * @@ -623,12 +623,12 @@ gsk_render_node_deserialize (GBytes *bytes, /** * gsk_value_set_render_node: - * @value: a `GValue` initialized with type `GSK_TYPE_RENDER_NODE` + * @value: a [struct@GObject.Value] initialized with type `GSK_TYPE_RENDER_NODE` * @node: a `GskRenderNode` * * Stores the given `GskRenderNode` inside `value`. * - * The `GValue` will acquire a reference to the `node`. + * The [struct@GObject.Value] will acquire a reference to the `node`. * * Since: 4.6 */ @@ -659,7 +659,7 @@ gsk_value_set_render_node (GValue *value, /** * gsk_value_take_render_node: - * @value: a `GValue` initialized with type `GSK_TYPE_RENDER_NODE` + * @value: a [struct@GObject.Value] initialized with type `GSK_TYPE_RENDER_NODE` * @node: (transfer full) (nullable): a `GskRenderNode` * * Stores the given `GskRenderNode` inside `value`. @@ -713,7 +713,7 @@ gsk_value_get_render_node (const GValue *value) /** * gsk_value_dup_render_node: - * @value: a `GValue` initialized with type `GSK_TYPE_RENDER_NODE` + * @value: a [struct@GObject.Value] initialized with type `GSK_TYPE_RENDER_NODE` * * Retrieves the `GskRenderNode` stored inside the given `value`, and acquires * a reference to it. From 1229032b4e557933e3efadca0df2fab37510ebd6 Mon Sep 17 00:00:00 2001 From: Maximiliano Sandoval R Date: Wed, 5 Jan 2022 12:44:23 +0100 Subject: [PATCH 5/5] docs: Add misc links --- gtk/css/gtkcsssection.h | 2 +- gtk/gtkpadcontroller.c | 10 +++++----- gtk/gtksizerequest.h | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/gtk/css/gtkcsssection.h b/gtk/css/gtkcsssection.h index 9d6f1ba055..e0ada752aa 100644 --- a/gtk/css/gtkcsssection.h +++ b/gtk/css/gtkcsssection.h @@ -36,7 +36,7 @@ G_BEGIN_DECLS * Defines a part of a CSS document. * * Because sections are nested into one another, you can use - * gtk_css_section_get_parent() to get the containing region. + * [method@CssSection.get_parent] to get the containing region. */ typedef struct _GtkCssSection GtkCssSection; diff --git a/gtk/gtkpadcontroller.c b/gtk/gtkpadcontroller.c index 49e7ae512e..d49dc00e10 100644 --- a/gtk/gtkpadcontroller.c +++ b/gtk/gtkpadcontroller.c @@ -28,7 +28,7 @@ * * These buttons and sensors have no implicit meaning, and by default they * perform no action. `GtkPadController` is provided to map those to - * `GAction` objects, thus letting the application give them a more + * [iface@Gio.Action] objects, thus letting the application give them a more * semantic meaning. * * Buttons and sensors are not constrained to triggering a single action, @@ -41,10 +41,10 @@ * different modes. See [method@Gdk.DevicePad.get_n_groups] and * [method@Gdk.DevicePad.get_group_n_modes]. * - * Each of the actions that a given button/strip/ring performs for a given - * mode is defined by a [struct@Gtk.PadActionEntry]. It contains an action - * name that will be looked up in the given `GActionGroup` and activated - * whenever the specified input element and mode are triggered. + * Each of the actions that a given button/strip/ring performs for a given mode + * is defined by a [struct@Gtk.PadActionEntry]. It contains an action name that + * will be looked up in the given [iface@Gio.ActionGroup] and activated whenever + * the specified input element and mode are triggered. * * A simple example of `GtkPadController` usage: Assigning button 1 in all * modes and pad devices to an "invert-selection" action: diff --git a/gtk/gtksizerequest.h b/gtk/gtksizerequest.h index 4f3b03d799..915e85e377 100644 --- a/gtk/gtksizerequest.h +++ b/gtk/gtksizerequest.h @@ -36,7 +36,7 @@ typedef struct _GtkRequestedSize GtkRequestedSize; * * Represents a request of a screen object in a given orientation. These * are primarily used in container implementations when allocating a natural - * size for children calling. See gtk_distribute_natural_allocation(). + * size for children calling. See [func@distribute_natural_allocation]. */ struct _GtkRequestedSize {