[gtk/docs-cleanup: 2/3] docs: Clean up many dangling links

[Matthias Clasen <matthiasc src gnome org>]

commit f5610001248a1328ca3b604da50b957ad5652a2d
Author: Matthias Clasen <mclasen redhat com>
Date:   Tue Aug 4 21:17:49 2020 -0400

    docs: Clean up many dangling links
    
    In many cases, these were references to no longer
    existing api, so some rewording was necessary.

 docs/reference/gtk/actions.md        |  7 ++---
 docs/reference/gtk/gtk4-sections.txt |  5 ++++
 docs/reference/gtk/input-handling.md |  2 +-
 docs/reference/gtk/question_index.md |  3 --
 gtk/gtkaboutdialog.c                 |  2 +-
 gtk/gtkatcontext.c                   |  2 +-
 gtk/gtkbitset.c                      |  6 ++--
 gtk/gtkbuilder.c                     | 15 ++++------
 gtk/gtkbuilderscope.h                |  2 +-
 gtk/gtkcellarea.c                    | 22 +++++++-------
 gtk/gtkcellrenderer.c                |  2 +-
 gtk/gtkcheckbutton.c                 |  2 +-
 gtk/gtkcolumnviewcolumn.c            |  2 +-
 gtk/gtkcombobox.c                    |  2 +-
 gtk/gtkdrawingarea.c                 | 13 ++++----
 gtk/gtkdroptargetasync.c             | 11 +++----
 gtk/gtkeditablelabel.c               | 10 +++----
 gtk/gtkentry.c                       | 16 +---------
 gtk/gtkenums.h                       | 19 +++++-------
 gtk/gtkeventcontroller.c             |  2 +-
 gtk/gtkeventcontrollerfocus.c        |  4 +--
 gtk/gtkexpression.c                  |  2 +-
 gtk/gtkfilechooser.c                 | 36 ++--------------------
 gtk/gtkfilefilter.c                  |  2 +-
 gtk/gtkfilter.c                      |  2 +-
 gtk/gtkgesture.c                     | 27 ++++++-----------
 gtk/gtkgestureclick.c                |  5 ----
 gtk/gtklistbox.c                     |  5 ++--
 gtk/gtkliststore.c                   |  2 +-
 gtk/gtknotebook.c                    | 16 ++++------
 gtk/gtkpagesetupunixdialog.c         |  2 +-
 gtk/gtkscrolledwindow.c              |  5 ++--
 gtk/gtkspinbutton.c                  |  2 +-
 gtk/gtkstylecontext.c                | 15 ++--------
 gtk/gtktextiter.c                    | 19 ++++++------
 gtk/gtktextview.c                    | 12 +-------
 gtk/gtktextview.h                    |  4 +--
 gtk/gtktogglebutton.c                |  2 +-
 gtk/gtktooltip.c                     | 15 +---------
 gtk/gtktreelistmodel.c               |  4 +--
 gtk/gtktreemodel.c                   |  2 +-
 gtk/gtkwidget.c                      | 58 ++++++++++++++++--------------------
 gtk/gtkwindow.c                      | 53 +++++++-------------------------
 43 files changed, 145 insertions(+), 294 deletions(-)
---
diff --git a/docs/reference/gtk/actions.md b/docs/reference/gtk/actions.md
index c88006e6d4..d2823370b0 100644
--- a/docs/reference/gtk/actions.md
+++ b/docs/reference/gtk/actions.md
@@ -185,10 +185,9 @@ is to create a menu using a GMenu menu model. GMenu provides an
 abstract way to describe typical menus: nested groups of items
 where each item can have a label, and icon, and an action.
 
-Typical uses of GMenu inside GTK are to set up an application
-menu or menubar with gtk_application_set_app_menu() or
-gtk_application_set_menubar(). Another, maybe more common use
-is to create a popover for a menubutton, using
+A typical use of GMenu inside GTK is to set up an application
+menubar with gtk_application_set_menubar(). Another, maybe more
+common use is to create a popover for a menubutton, using
 gtk_menu_button_set_menu_model().
 
 Unlike traditional menus, those created from menu models don't
diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt
index 0efe0d7da7..f6d3463a62 100644
--- a/docs/reference/gtk/gtk4-sections.txt
+++ b/docs/reference/gtk/gtk4-sections.txt
@@ -644,6 +644,7 @@ gtk_grid_view_get_type
 <FILE>gtkbuildable</FILE>
 GtkBuildable
 GtkBuildableIface
+GtkBuildableParser
 gtk_buildable_set_name
 gtk_buildable_get_name
 gtk_buildable_add_child
@@ -666,6 +667,10 @@ GTK_BUILDABLE_GET_IFACE
 <SECTION>
 <FILE>gtkbuilderscope</FILE>
 <TITLE>GtkBuilderScope</TITLE>
+GtkBuilderScope
+GtkBuilderClosureFlags
+GtkBuilderScopeInterface
+GtkBuilderCScope
 gtk_builder_cscope_new
 gtk_builder_cscope_add_callback_symbol
 gtk_builder_cscope_add_callback_symbols
diff --git a/docs/reference/gtk/input-handling.md b/docs/reference/gtk/input-handling.md
index 1404238489..35376f7cb7 100644
--- a/docs/reference/gtk/input-handling.md
+++ b/docs/reference/gtk/input-handling.md
@@ -66,7 +66,7 @@ the target widget for event propagation is window's current focus
 widget (see gtk_window_get_focus()).
 
 For pointer events, the target widget is determined by picking
-the widget at the events coordinates (see gtk_window_pick()).
+the widget at the events coordinates (see gtk_widget_pick()).
 
 In the first phase (the “capture” phase) the event is delivered to
 each widget from the top-most (the top-level #GtkWindow or grab widget)
diff --git a/docs/reference/gtk/question_index.md b/docs/reference/gtk/question_index.md
index 7175090fc1..6386e2f78f 100644
--- a/docs/reference/gtk/question_index.md
+++ b/docs/reference/gtk/question_index.md
@@ -412,9 +412,6 @@ the question you have, this list is a good place to start.
     text typed in by the user before or after the tagged block will appear in
     the default style.
 
-    To ensure that all text has the desired appearance, use
-    gtk_widget_override_font() to change the default font for the widget.
-
 25. How do I make a text view scroll to the end of the buffer automatically ?
 
     A good way to keep a text buffer scrolled to the end is to place a
diff --git a/gtk/gtkaboutdialog.c b/gtk/gtkaboutdialog.c
index 7c1a1b0e81..66887e2b66 100644
--- a/gtk/gtkaboutdialog.c
+++ b/gtk/gtkaboutdialog.c
@@ -567,7 +567,7 @@ gtk_about_dialog_class_init (GtkAboutDialogClass *klass)
    * GtkAboutDialog:logo:
    *
    * A logo for the about box. If it is %NULL, the default window icon
-   * set with gtk_window_set_default_icon() will be used.
+   * set with gtk_window_set_default_icon_name() will be used.
    */
   props[PROP_LOGO] =
     g_param_spec_object ("logo",
diff --git a/gtk/gtkatcontext.c b/gtk/gtkatcontext.c
index 0f12bf9121..c18a6cff37 100644
--- a/gtk/gtkatcontext.c
+++ b/gtk/gtkatcontext.c
@@ -177,7 +177,7 @@ gtk_at_context_class_init (GtkATContextClass *klass)
    * @self: the #GtkATContext
    * @changed_states: flags for the changed states
    * @changed_properties: flags for the changed properties
-   * @changed_relations:
+   * @changed_relations: flags for the changed relations
    * @states: the new states
    * @properties: the new properties
    * @relations: the new relations
diff --git a/gtk/gtkbitset.c b/gtk/gtkbitset.c
index 1d39918639..7a390aaddd 100644
--- a/gtk/gtkbitset.c
+++ b/gtk/gtkbitset.c
@@ -194,9 +194,9 @@ gtk_bitset_get_maximum (const GtkBitset *self)
 
 /**
  * gtk_bitset_get_size:
- * @self: a #GtkBitSet
+ * @self: a #GtkBitset
  *
- * Gets the number of values that were added to the set.  
+ * Gets the number of values that were added to the set.
  * For example, if the set is empty, 0 is returned.
  *
  * Note that this function returns a #guint64, because when all values are
@@ -215,7 +215,7 @@ gtk_bitset_get_size (const GtkBitset *self)
 
 /**
  * gtk_bitset_get_size_in_range:
- * @self: a #GtkBitSet
+ * @self: a #GtkBitset
  * @first: the first element to include
  * @last: the last element to include
  *
diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c
index a3ee15dfde..6c5f5469f0 100644
--- a/gtk/gtkbuilder.c
+++ b/gtk/gtkbuilder.c
@@ -53,9 +53,6 @@
  * Non-widget objects need to be reffed with g_object_ref() to keep them
  * beyond the lifespan of the builder.
  *
- * The function gtk_builder_connect_signals() and variants thereof can be
- * used to connect handlers to the named signals in the description.
- *
  * # GtkBuilder UI Definitions # {#BUILDER-UI}
  *
  * GtkBuilder parses textual descriptions of user interfaces which are
@@ -2717,14 +2714,12 @@ _gtk_builder_get_template_type (GtkBuilder *builder)
  * @object: (nullable): Object to create the closure with
  * @error: (allow-none): return location for an error, or %NULL
  *
- * Creates a closure to invoke the function called @function_name.
- *
- * If a closure function was set via gtk_builder_set_closure_func(),
- * will be invoked.
- * Otherwise, gtk_builder_create_cclosure() will be called.
+ * Creates a closure to invoke the function called @function_name,
+ * by using the create_closure() implementation of @builder's
+ * #GtkBuilderScope.
  *
- * If no closure could be created, %NULL will be returned and @error will
- * be set.
+ * If no closure could be created, %NULL will be returned and @error
+ * will be set.
  *
  * Returns: (nullable): A new closure for invoking @function_name
  **/
diff --git a/gtk/gtkbuilderscope.h b/gtk/gtkbuilderscope.h
index 23f44fd485..e08adaf6fc 100644
--- a/gtk/gtkbuilderscope.h
+++ b/gtk/gtkbuilderscope.h
@@ -38,7 +38,7 @@ G_DECLARE_INTERFACE (GtkBuilderScope, gtk_builder_scope, GTK, BUILDER_SCOPE, GOb
  * @GTK_BUILDER_CLOSURE_SWAPPED: The closure should be created swapped. See
  *   g_cclosure_new_swap() for details.
  *
- * The list of flags that can be passed to gtk_builder_scope_create_closure().
+ * The list of flags that can be passed to gtk_builder_create_closure().
  * New values may be added in the future for new features, so external
  * implementations of GtkBuilderScopeInterface should test the flags for unknown
  * values and raise a %@GTK_BUILDER_ERROR_INVALID_ATTRIBUTE error when they
diff --git a/gtk/gtkcellarea.c b/gtk/gtkcellarea.c
index d59aa41295..e0ce9e48e6 100644
--- a/gtk/gtkcellarea.c
+++ b/gtk/gtkcellarea.c
@@ -101,7 +101,7 @@
  * exceedingly large amount of rows. The #GtkCellLayout widget in
  * that case would calculate the required width of the rows in an
  * idle or timeout source (see g_timeout_add()) and when the widget
- * is requested its actual width in #GtkWidgetClass.get_preferred_width()
+ * is requested its actual width in #GtkWidgetClass.measure()
  * it can simply consult the width accumulated so far in the
  * #GtkCellAreaContext object.
  *
@@ -177,7 +177,7 @@
  * synchronously. The reasoning here is that any layouting widget is
  * at least capable of synchronously calculating enough height to fill
  * the screen height (or scrolled window height) in response to a single
- * call to #GtkWidgetClass.get_preferred_height_for_width(). Returning
+ * call to #GtkWidgetClass.measure(). Returning
  * a perfect height for width that is larger than the screen area is
  * inconsequential since after the layouting receives an allocation
  * from a scrolled window it simply continues to drive the scrollbar
@@ -188,7 +188,7 @@
  *
  * Once area sizes have been aquired at least for the rows in the
  * visible area of the layouting widget they can be rendered at
- * #GtkWidgetClass.draw() time.
+ * #GtkWidgetClass.snapshot() time.
  *
  * A crude example of how to render all the rows at the root level
  * runs as follows:
@@ -318,15 +318,13 @@
  *
  * # Cell Properties
  *
- * The #GtkCellArea introduces cell properties for #GtkCellRenderers
- * in very much the same way that #GtkContainer introduces
- * [child properties][child-properties]
- * for #GtkWidgets. This provides some general interfaces for defining
- * the relationship cell areas have with their cells. For instance in a
- * #GtkCellAreaBox a cell might “expand” and receive extra space when
- * the area is allocated more than its full natural request, or a cell
- * might be configured to “align” with adjacent rows which were requested
- * and rendered with the same #GtkCellAreaContext.
+ * The #GtkCellArea introduces cell properties for #GtkCellRenderers.
+ * This provides some general interfaces for defining the relationship
+ * cell areas have with their cells. For instance in a #GtkCellAreaBox
+ * a cell might “expand” and receive extra space when the area is allocated
+ * more than its full natural request, or a cell might be configured to “align”
+ * with adjacent rows which were requested and rendered with the same
+ * #GtkCellAreaContext.
  *
  * Use gtk_cell_area_class_install_cell_property() to install cell
  * properties for a cell area class and gtk_cell_area_class_find_cell_property()
diff --git a/gtk/gtkcellrenderer.c b/gtk/gtkcellrenderer.c
index b0dcdc9caf..ed9be3e10b 100644
--- a/gtk/gtkcellrenderer.c
+++ b/gtk/gtkcellrenderer.c
@@ -50,7 +50,7 @@
  * There are a number of rules that must be followed when writing a new
  * #GtkCellRenderer.  First and foremost, it’s important that a certain set
  * of properties will always yield a cell renderer of the same size,
- * barring a #GtkStyle change.  The #GtkCellRenderer also has a number of
+ * barring a style change. The #GtkCellRenderer also has a number of
  * generic properties that are expected to be honored by all children.
  *
  * Beyond merely rendering a cell, cell renderers can optionally
diff --git a/gtk/gtkcheckbutton.c b/gtk/gtkcheckbutton.c
index 6c5dcdc375..c6db13518f 100644
--- a/gtk/gtkcheckbutton.c
+++ b/gtk/gtkcheckbutton.c
@@ -44,7 +44,7 @@
  * SECTION:gtkcheckbutton
  * @Short_description: Create widgets with a discrete toggle button
  * @Title: GtkCheckButton
- * @See_also: #GtkCheckMenuItem, #GtkButton, #GtkToggleButton, #GtkRadioButton
+ * @See_also: #GtkButton, #GtkToggleButton, #GtkRadioButton
  *
  * A #GtkCheckButton places a discrete #GtkToggleButton next to a widget,
  * (usually a #GtkLabel). See the section on #GtkToggleButton widgets for
diff --git a/gtk/gtkcolumnviewcolumn.c b/gtk/gtkcolumnviewcolumn.c
index 3ee4b84123..f9d0d64246 100644
--- a/gtk/gtkcolumnviewcolumn.c
+++ b/gtk/gtkcolumnviewcolumn.c
@@ -360,7 +360,7 @@ gtk_column_view_column_init (GtkColumnViewColumn *self)
  *
  * Creates a new #GtkColumnViewColumn.
  *
- * You most likely want to call gtk_column_add_column() next.
+ * You most likely want to call gtk_column_view_add_column() next.
  *
  * Returns: a new #GtkColumnViewColumn
  **/
diff --git a/gtk/gtkcombobox.c b/gtk/gtkcombobox.c
index 015fe479d6..1050dde853 100644
--- a/gtk/gtkcombobox.c
+++ b/gtk/gtkcombobox.c
@@ -66,7 +66,7 @@
  *
  * To allow the user to enter values not in the model, the “has-entry”
  * property allows the GtkComboBox to contain a #GtkEntry. This entry
- * can be accessed by calling gtk_bin_get_child() on the combo box.
+ * can be accessed by calling gtk_combo_box_get_child() on the combo box.
  *
  * For a simple list of textual choices, the model-view API of GtkComboBox
  * can be a bit overwhelming. In this case, #GtkComboBoxText offers a
diff --git a/gtk/gtkdrawingarea.c b/gtk/gtkdrawingarea.c
index 65c7198d3c..80753fa27c 100644
--- a/gtk/gtkdrawingarea.c
+++ b/gtk/gtkdrawingarea.c
@@ -131,16 +131,13 @@ static guint signals[LAST_SIGNAL] = { 0, };
  * This will cause the drawing area to call the draw function again.
  *
  * The available routines for drawing are documented on the
- * [GDK Drawing Primitives][gdk3-Cairo-Interaction] page
+ * [GDK Drawing Primitives][gdk4-Cairo-Interaction] page
  * and the cairo documentation.
  *
- * To receive mouse events on a drawing area, you will need to enable
- * them with gtk_widget_add_events(). To receive keyboard events, you
- * will need to set the “can-focus” property on the drawing area, and you
- * should probably draw some user-visible indication that the drawing
- * area is focused. Use gtk_widget_has_focus() in your expose event
- * handler to decide whether to draw the focus indicator. See
- * gtk_render_focus() for one way to draw focus.
+ * To receive mouse events on a drawing area, you will need to use
+ * event controllers. To receive keyboard events, you will need to set
+ * the “can-focus” property on the drawing area, and you should probably
+ * draw some user-visible indication that the drawing area is focused.
  *
  * If you need more complex control over your widget, you should consider
  * creating your own #GtkWidget subclass.
diff --git a/gtk/gtkdroptargetasync.c b/gtk/gtkdroptargetasync.c
index 3a8c7b36e3..c14d307096 100644
--- a/gtk/gtkdroptargetasync.c
+++ b/gtk/gtkdroptargetasync.c
@@ -410,11 +410,12 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class)
    * @drop: the #GdkDrop
    *
    * The ::accept signal is emitted on the drop site when a drop operation
-   * is about to begin.  
+   * is about to begin.
+   *
    * If the drop is not accepted, %FALSE will be returned and the drop target
    * will ignore the drop. If %TRUE is returned, the drop is accepted for now
-   * but may be rejected later via a call to gtk_drop_target_reject() or
-   * ultimately by returning %FALSE from GtkDropTarget::drop
+   * but may be rejected later via a call to gtk_drop_target_async_reject() or
+   * ultimately by returning %FALSE from #GtkDropTargetAsync::drop.
    *
    * The default handler for this signal decides whether to accept the drop
    * based on the formats provided by the @drop.
@@ -422,7 +423,7 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class)
    * If the decision whether the drop will be accepted or rejected needs
    * further processing, such as inspecting the data, this function should
    * return %TRUE and proceed as is @drop was accepted and if it decides to
-   * reject the drop later, it should call gtk_drop_target_reject_drop().
+   * reject the drop later, it should call gtk_drop_target_async_reject_drop().
    *
    * Returns: %TRUE if @drop is accepted
    */
@@ -514,7 +515,7 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class)
    * Otherwise, the handler returns %TRUE. In this case, this handler will
    * accept the drop. The handler must ensure that gdk_drop_finish() is
    * called to let the source know that the drop is done. The call to
-   * gtk_drag_finish() must only be done when all data has been received.
+   * gdk_drop_finish() must only be done when all data has been received.
    *
    * To receive the data, use one of the read functions provides by #GdkDrop
    * such as gdk_drop_read_async() or gdk_drop_read_value_async().
diff --git a/gtk/gtkeditablelabel.c b/gtk/gtkeditablelabel.c
index 52ca9f3e82..959d0428d8 100644
--- a/gtk/gtkeditablelabel.c
+++ b/gtk/gtkeditablelabel.c
@@ -143,7 +143,7 @@ text_changed (GtkEditableLabel *self)
   /* Sync the entry text to the label, unless we are editing.
    *
    * This is necessary to catch apis like gtk_editable_insert_text(),
-   * which don't go through the ::text property.
+   * which don't go through the text property.
    */
   if (!gtk_editable_label_get_editing (self))
     {
@@ -384,7 +384,7 @@ gtk_editable_label_class_init (GtkEditableLabelClass *class)
    * The default bindings for this action are clicking
    * on the widget and the Enter key.
    *
-   * This action is disabled when #GtkEditable:editing
+   * This action is disabled when #GtkEditableLabel:editing
    * is %FALSE.
    */
   gtk_widget_class_install_action (widget_class, "editing.start", NULL, start_editing);
@@ -400,7 +400,7 @@ gtk_editable_label_class_init (GtkEditableLabelClass *class)
    * The default binding for this action is the Escape
    * key.
    *
-   * This action is disabled when #GtkEditable:editing
+   * This action is disabled when #GtkEditableLabel:editing
    * is %FALSE.
    */
   gtk_widget_class_install_action (widget_class, "editing.stop", "b", stop_editing);
@@ -484,9 +484,9 @@ gtk_editable_label_start_editing (GtkEditableLabel *self)
  * @commit: whether to set the edited text on the label
  *
  * Switches the label out of “editing mode”. If @commit is %TRUE,
- * the resulting text is kept as the #GtkEditableLabel:text property
+ * the resulting text is kept as the #GtkEditable:text property
  * value, otherwise the resulting text is discarded and the label
- * will keep its previous #GtkEditableLabel:text property value.
+ * will keep its previous #GtkEditable:text property value.
  */
 void
 gtk_editable_label_stop_editing (GtkEditableLabel *self,
diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c
index f4acb4c17a..ee4de399d3 100644
--- a/gtk/gtkentry.c
+++ b/gtk/gtkentry.c
@@ -2834,19 +2834,8 @@ gtk_entry_get_icon_at_pos (GtkEntry *entry,
  * @provider: a #GdkContentProvider
  * @actions: a bitmask of the allowed drag actions
  *
- * Sets up the icon at the given position so that GTK+ will start a drag
+ * Sets up the icon at the given position so that GTK will start a drag
  * operation when the user clicks and drags the icon.
- *
- * To handle the drag operation, you need to connect to the usual
- * #GtkWidget::drag-data-get (or possibly #GtkWidget::drag-data-delete)
- * signal, and use gtk_entry_get_current_icon_drag_source() in
- * your signal handler to find out if the drag was started from
- * an icon.
- *
- * By default, GTK+ uses the icon as the drag icon. You can use the 
- * #GtkWidget::drag-begin signal to set a different icon. Note that you 
- * have to use g_signal_connect_after() to ensure that your signal handler
- * gets executed after the default handler.
  */
 void
 gtk_entry_set_icon_drag_source (GtkEntry             *entry,
@@ -2874,9 +2863,6 @@ gtk_entry_set_icon_drag_source (GtkEntry             *entry,
  * Returns the index of the icon which is the source of the current
  * DND operation, or -1.
  *
- * This function is meant to be used in a #GtkWidget::drag-data-get
- * callback.
- *
  * Returns: index of the icon which is the source of the current
  *          DND operation, or -1.
  */
diff --git a/gtk/gtkenums.h b/gtk/gtkenums.h
index d8dbe725b0..d39b867881 100644
--- a/gtk/gtkenums.h
+++ b/gtk/gtkenums.h
@@ -58,9 +58,9 @@ G_BEGIN_DECLS
  * dimension.
  *
  * Alignment only matters if the widget receives a “too large” allocation,
- * for example if you packed the widget with the #GtkWidget:expand
- * flag inside a #GtkBox, then the widget might get extra space.  If
- * you have for example a 16x16 icon inside a 32x32 space, the icon
+ * for example if you packed the widget with the #GtkWidget:hexpand
+ * property inside a #GtkBox, then the widget might get extra space.
+ * If you have for example a 16x16 icon inside a 32x32 space, the icon
  * could be scaled and stretched, it could be centered, or it could be
  * positioned to one side of the space.
  *
@@ -234,8 +234,7 @@ typedef enum
  * @GTK_JUSTIFY_CENTER: The text is placed in the center of the label.
  * @GTK_JUSTIFY_FILL: The text is placed is distributed across the label.
  *
- * Used for justifying the text inside a #GtkLabel widget. (See also
- * #GtkAlignment).
+ * Used for justifying the text inside a #GtkLabel widget.
  */
 typedef enum
 {
@@ -379,9 +378,8 @@ typedef enum
  * @GTK_POS_TOP: The feature is at the top edge.
  * @GTK_POS_BOTTOM: The feature is at the bottom edge.
  *
- * Describes which edge of a widget a certain feature is positioned at, e.g. the
- * tabs of a #GtkNotebook, the handle of a #GtkHandleBox or the label of a
- * #GtkScale.
+ * Describes which edge of a widget a certain feature is positioned at, e.g.
+ * the tabs of a #GtkNotebook, or the label of a #GtkScale.
  */
 typedef enum
 {
@@ -897,10 +895,7 @@ typedef enum
 
 /**
  * GtkPropagationPhase:
- * @GTK_PHASE_NONE: Events are not delivered automatically. Those can be
- *   manually fed through gtk_event_controller_handle_event(). This should
- *   only be used when full control about when, or whether the controller
- *   handles the event is needed.
+ * @GTK_PHASE_NONE: Events are not delivered.
  * @GTK_PHASE_CAPTURE: Events are delivered in the capture phase. The
  *   capture phase happens before the bubble phase, runs from the toplevel down
  *   to the event widget. This option should only be used on containers that
diff --git a/gtk/gtkeventcontroller.c b/gtk/gtkeventcontroller.c
index 432990ed91..68670a8e14 100644
--- a/gtk/gtkeventcontroller.c
+++ b/gtk/gtkeventcontroller.c
@@ -316,7 +316,7 @@ gtk_event_controller_filter_crossing (GtkEventController    *controller,
   return FALSE;
 }
 
-/**
+/*
  * gtk_event_controller_handle_event:
  * @controller: a #GtkEventController
  * @event: a #GdkEvent
diff --git a/gtk/gtkeventcontrollerfocus.c b/gtk/gtkeventcontrollerfocus.c
index 46c8faba91..a59f9f6f5e 100644
--- a/gtk/gtkeventcontrollerfocus.c
+++ b/gtk/gtkeventcontrollerfocus.c
@@ -190,8 +190,8 @@ gtk_event_controller_focus_class_init (GtkEventControllerFocusClass *klass)
    * #GtkEventControllerFocus:contains-focus.
    *
    * When handling focus events, this property is updated
-   * before #GtkEventControllerKey::focus-in or
-   * #GtkEventControllerKey::focus-out are emitted.
+   * before #GtkEventControllerFocus::enter or
+   * #GtkEventControllerFocus::leave are emitted.
    */
   props[PROP_IS_FOCUS] =
       g_param_spec_boolean ("is-focus",
diff --git a/gtk/gtkexpression.c b/gtk/gtkexpression.c
index fada1d1d03..81e1207b40 100644
--- a/gtk/gtkexpression.c
+++ b/gtk/gtkexpression.c
@@ -1652,7 +1652,7 @@ GTK_DEFINE_EXPRESSION_TYPE (GtkCClosureExpression,
  * @user_destroy: (nullable): destroy notify for @user_data
  *
  * This function is a variant of gtk_closure_expression_new() that
- * creates a #GClosure by calling gtk_cclosure_new() with the given
+ * creates a #GClosure by calling g_cclosure_new() with the given
  * @callback_func, @user_data and @user_destroy.
  *
  * Returns: a new #GtkExpression
diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index da188eb4f7..bd31cf90ae 100644
--- a/gtk/gtkfilechooser.c
+++ b/gtk/gtkfilechooser.c
@@ -119,7 +119,7 @@ gtk_file_chooser_default_init (GtkFileChooserInterface *iface)
    * GtkFileChooser:shortcut-folders:
    *
    * A #GListModel containing the shortcut folders that have been
-   * added with gtk_file_chooser_add_shortcut().
+   * added with gtk_file_chooser_add_shortcut_folder().
    *
    * The returned object should not be modified. It may
    * or may not be updated for later changes.
@@ -328,12 +328,6 @@ gtk_file_chooser_get_current_name (GtkFileChooser *chooser)
   return GTK_FILE_CHOOSER_GET_IFACE (chooser)->get_current_name (chooser);
 }
 
-/**
- * gtk_file_chooser_select_all:
- * @chooser: a #GtkFileChooser
- * 
- * Selects all the files in the current folder of a file chooser.
- **/
 void
 gtk_file_chooser_select_all (GtkFileChooser *chooser)
 {
@@ -342,12 +336,6 @@ gtk_file_chooser_select_all (GtkFileChooser *chooser)
   GTK_FILE_CHOOSER_GET_IFACE (chooser)->select_all (chooser);
 }
 
-/**
- * gtk_file_chooser_unselect_all:
- * @chooser: a #GtkFileChooser
- * 
- * Unselects all the files in the current folder of a file chooser.
- **/
 void
 gtk_file_chooser_unselect_all (GtkFileChooser *chooser)
 {
@@ -396,16 +384,6 @@ gtk_file_chooser_get_current_folder (GtkFileChooser *chooser)
   return GTK_FILE_CHOOSER_GET_IFACE (chooser)->get_current_folder (chooser);
 }
 
-/**
- * gtk_file_chooser_select_file:
- * @chooser: a #GtkFileChooser
- * @file: the file to select
- * @error: (allow-none): location to store error, or %NULL
- * 
- * Selects the file referred to by @file.
- *
- * Returns: Not useful.
- **/
 gboolean
 gtk_file_chooser_select_file (GtkFileChooser  *chooser,
                               GFile           *file,
@@ -418,14 +396,6 @@ gtk_file_chooser_select_file (GtkFileChooser  *chooser,
   return GTK_FILE_CHOOSER_GET_IFACE (chooser)->select_file (chooser, file, error);
 }
 
-/**
- * gtk_file_chooser_unselect_file:
- * @chooser: a #GtkFileChooser
- * @file: a #GFile
- * 
- * Unselects the file referred to by @file. If the file is not in the current
- * directory, does not exist, or is otherwise not currently selected, does nothing.
- **/
 void
 gtk_file_chooser_unselect_file (GtkFileChooser *chooser,
                                 GFile          *file)
@@ -467,9 +437,7 @@ gtk_file_chooser_get_files (GtkFileChooser *chooser)
  * will also appear in the dialog’s file name entry.
  *
  * If the file name isn’t in the current folder of @chooser, then the current
- * folder of @chooser will be changed to the folder containing @filename. This
- * is equivalent to a sequence of gtk_file_chooser_unselect_all() followed by
- * gtk_file_chooser_select_filename().
+ * folder of @chooser will be changed to the folder containing @filename.
  *
  * Note that the file must exist, or nothing will be done except
  * for the directory change.
diff --git a/gtk/gtkfilefilter.c b/gtk/gtkfilefilter.c
index 9cd3bde6ad..d2ef36c7aa 100644
--- a/gtk/gtkfilefilter.c
+++ b/gtk/gtkfilefilter.c
@@ -611,7 +611,7 @@ gtk_file_filter_add_pixbuf_formats (GtkFileFilter *filter)
  * @filter: a #GtkFileFilter
  *
  * Gets the attributes that need to be filled in for the #GFileInfo
- * passed to gtk_file_filter_filter()
+ * passed to this filter.
  *
  * This function will not typically be used by applications;
  * it is intended principally for use in the implementation
diff --git a/gtk/gtkfilter.c b/gtk/gtkfilter.c
index 096b7aeb06..2d76f8ff1c 100644
--- a/gtk/gtkfilter.c
+++ b/gtk/gtkfilter.c
@@ -28,7 +28,7 @@
  * SECTION:gtkfilter
  * @Title: GtkFilter
  * @Short_description: Filtering items
- * @See_also: #GtkFilerListModel
+ * @See_also: #GtkFilterListModel
  *
  * A #GtkFilter object describes the filtering to be performed by a
  * #GtkFilterListModel.
diff --git a/gtk/gtkgesture.c b/gtk/gtkgesture.c
index ce40044901..1a791d3339 100644
--- a/gtk/gtkgesture.c
+++ b/gtk/gtkgesture.c
@@ -34,10 +34,9 @@
  * or more than that number of sequences, it won't check wether the gesture
  * is recognized.
  *
- * As soon as the gesture has the expected number of touches, the gesture will
- * run the #GtkGesture::check signal regularly on input events until the gesture
- * is recognized, the criteria to consider a gesture as "recognized" is left to
- * #GtkGesture subclasses.
+ * As soon as the gesture has the expected number of touches, it will check
+ * regularly if it is recognized, the criteria to consider a gesture as
+ * "recognized" is left to #GtkGesture subclasses.
  *
  * A recognized gesture will then emit the following signals:
  * - #GtkGesture::begin when the gesture is recognized.
@@ -46,18 +45,13 @@
  *
  * ## Event propagation
  *
- * In order to receive events, a gesture needs to either set a propagation phase
- * through gtk_event_controller_set_propagation_phase(), or feed those manually
- * through gtk_event_controller_handle_event().
+ * In order to receive events, a gesture needs to set a propagation phase
+ * through gtk_event_controller_set_propagation_phase().
  *
  * In the capture phase, events are propagated from the toplevel down to the
  * target widget, and gestures that are attached to containers above the widget
  * get a chance to interact with the event before it reaches the target.
  *
- * After the capture phase, GTK+ emits the traditional #GtkWidget::event signal.
- * Gestures with the %GTK_PHASE_TARGET phase are fed events from the default
- * #GtkWidget::event handlers.
- *
  * In the bubble phase, events are propagated up from the target widget to the
  * toplevel, and gestures that are attached to containers above the widget get
  * a chance to interact with events that have not been handled yet.
@@ -772,8 +766,7 @@ gtk_gesture_class_init (GtkGestureClass *klass)
    * @sequence: the #GdkEventSequence that made the gesture to be recognized
    *
    * This signal is emitted when the gesture is recognized. This means the
-   * number of touch sequences matches #GtkGesture:n-points, and the #GtkGesture::check
-   * handler(s) returned #TRUE.
+   * number of touch sequences matches #GtkGesture:n-points.
    *
    * Note: These conditions may also happen when an extra touch (eg. a third touch
    * on a 2-touches gesture) is lifted, in that situation @sequence won't pertain
@@ -792,9 +785,8 @@ gtk_gesture_class_init (GtkGestureClass *klass)
    * @sequence: the #GdkEventSequence that made gesture recognition to finish
    *
    * This signal is emitted when @gesture either stopped recognizing the event
-   * sequences as something to be handled (the #GtkGesture::check handler returned
-   * %FALSE), or the number of touch sequences became higher or lower than
-   * #GtkGesture:n-points.
+   * sequences as something to be handled, or the number of touch sequences became
+   * higher or lower than #GtkGesture:n-points.
    *
    * Note: @sequence might not pertain to the group of sequences that were
    * previously triggering recognition on @gesture (ie. a just pressed touch
@@ -1383,8 +1375,7 @@ gtk_gesture_is_active (GtkGesture *gesture)
  *
  * Returns %TRUE if the gesture is currently recognized.
  * A gesture is recognized if there are as many interacting
- * touch sequences as required by @gesture, and #GtkGesture::check
- * returned %TRUE for the sequences being currently interpreted.
+ * touch sequences as required by @gesture.
  *
  * Returns: %TRUE if gesture is recognized
  **/
diff --git a/gtk/gtkgestureclick.c b/gtk/gtkgestureclick.c
index 27f6e1367a..3194fec59c 100644
--- a/gtk/gtkgestureclick.c
+++ b/gtk/gtkgestureclick.c
@@ -27,11 +27,6 @@
  * the #GtkGestureClick::pressed signal. Whenever time or distance
  * between clicks exceed the GTK+ defaults, #GtkGestureClick::stopped
  * is emitted, and the click counter is reset.
- *
- * Callers may also restrict the area that is considered valid for a >1
- * touch/button press through gtk_gesture_click_set_area(), so any
- * click happening outside that area is considered to be a first click
- * of its own.
  */
 
 #include "config.h"
diff --git a/gtk/gtklistbox.c b/gtk/gtklistbox.c
index 9283312722..fd0a86e4d2 100644
--- a/gtk/gtklistbox.c
+++ b/gtk/gtklistbox.c
@@ -2690,8 +2690,9 @@ gtk_list_box_drag_unhighlight_row (GtkListBox *box)
  * @row: a #GtkListBoxRow
  *
  * This is a helper function for implementing DnD onto a #GtkListBox.
- * The passed in @row will be highlighted via gtk_drag_highlight(),
- * and any previously highlighted row will be unhighlighted.
+ * The passed in @row will be highlighted by setting the
+ * #GTK_STATE_FLAG_DROP_ACTIVE state and any previously highlighted
+ * row will be unhighlighted.
  *
  * The row will also be unhighlighted when the widget gets
  * a drag leave event.
diff --git a/gtk/gtkliststore.c b/gtk/gtkliststore.c
index e27feedc52..fa5fdc725a 100644
--- a/gtk/gtkliststore.c
+++ b/gtk/gtkliststore.c
@@ -40,7 +40,7 @@
  * can use all of the methods available there.  It also implements the
  * #GtkTreeSortable interface so it can be sorted by the view.
  * Finally, it also implements the tree
- * [drag and drop][gtk3-GtkTreeView-drag-and-drop]
+ * [drag and drop][gtk4-GtkTreeView-drag-and-drop]
  * interfaces.
  *
  * The #GtkListStore can accept most GObject types as a column type, though
diff --git a/gtk/gtknotebook.c b/gtk/gtknotebook.c
index ddcb9d64b9..95108c1dd0 100644
--- a/gtk/gtknotebook.c
+++ b/gtk/gtknotebook.c
@@ -63,10 +63,9 @@
  * SECTION:gtknotebook
  * @Short_description: A tabbed notebook container
  * @Title: GtkNotebook
- * @See_also: #GtkContainer
  *
- * The #GtkNotebook widget is a #GtkContainer whose children are pages that
- * can be switched between using tab labels along one edge.
+ * The #GtkNotebook widget is a layout container whose children are
+ * pages that can be switched between using tab labels along one edge.
  *
  * There are many configuration options for GtkNotebook. Among other
  * things, you can choose on which edge the tabs appear
@@ -3304,7 +3303,7 @@ gtk_notebook_drag_drop (GtkDropTarget *dest,
  *
  * Removes the child from the notebook.
  *
- * This function is very similar to gtk_container_remove(),
+ * This function is very similar to gtk_notebook_remove_page(),
  * but additionally informs the notebook that the removal
  * is happening as part of a tab DND operation, which should
  * not be cancelled.
@@ -3375,7 +3374,7 @@ do_detach_tab (GtkNotebook *from,
   gtk_notebook_set_current_page (to, page_num);
 }
 
-/* Private GtkContainer Methods :
+/* Private methods:
  *
  * gtk_notebook_remove
  * gtk_notebook_focus
@@ -6887,8 +6886,8 @@ gtk_notebook_get_tab_detachable (GtkNotebook *notebook,
  * will fill the selection with a GtkWidget** pointing to the child
  * widget that corresponds to the dropped tab.
  *
- * Note that you should use gtk_notebook_detach_tab() instead
- * of gtk_container_remove() if you want to remove the tab from
+ * Note that you should use gtk_notebook_detach_tab() instead of
+ * gtk_notebook_remove_page() if you want to remove the tab from
  * the source notebook as part of accepting a drop. Otherwise,
  * the source notebook will think that the dragged tab was
  * removed from underneath the ongoing drag operation, and
@@ -6971,9 +6970,6 @@ gtk_notebook_get_action_widget (GtkNotebook *notebook,
  * Sets @widget as one of the action widgets. Depending on the pack type
  * the widget will be placed before or after the tabs. You can use
  * a #GtkBox if you need to pack more than one widget on the same side.
- *
- * Note that action widgets are “internal” children of the notebook and thus
- * not included in the list returned from gtk_container_foreach().
  */
 void
 gtk_notebook_set_action_widget (GtkNotebook *notebook,
diff --git a/gtk/gtkpagesetupunixdialog.c b/gtk/gtkpagesetupunixdialog.c
index a6afe27679..6cce41b50f 100644
--- a/gtk/gtkpagesetupunixdialog.c
+++ b/gtk/gtkpagesetupunixdialog.c
@@ -50,7 +50,7 @@
  * which don’t provide a native page setup dialog, like Unix. It can
  * be used very much like any other GTK dialog, at the cost of
  * the portability offered by the
- * [high-level printing API][gtk3-High-level-Printing-API]
+ * [high-level printing API][gtk4-High-level-Printing-API]
  */
 
 typedef struct _GtkPageSetupUnixDialogClass    GtkPageSetupUnixDialogClass;
diff --git a/gtk/gtkscrolledwindow.c b/gtk/gtkscrolledwindow.c
index 7af5ce0563..13a5803ca6 100644
--- a/gtk/gtkscrolledwindow.c
+++ b/gtk/gtkscrolledwindow.c
@@ -2559,9 +2559,8 @@ gtk_scrolled_window_get_kinetic_scrolling (GtkScrolledWindow *scrolled_window)
  * then later replayed if it is meant to go to the child widget.
  *
  * This should be enabled if any child widgets perform non-reversible
- * actions on button press events. If they don't, and additionally handle
- * #GtkWidget::grab-broken-event, it might be better to set @capture_button_press
- * to %FALSE.
+ * actions on button press events. If they don't, it might be better to
+ * set @capture_button_press to %FALSE.
  *
  * This setting only has an effect if kinetic scrolling is enabled.
  */
diff --git a/gtk/gtkspinbutton.c b/gtk/gtkspinbutton.c
index 6c2cbc4f16..01466dda23 100644
--- a/gtk/gtkspinbutton.c
+++ b/gtk/gtkspinbutton.c
@@ -88,7 +88,7 @@
  * Note that GtkSpinButton will by default make its entry large enough to
  * accomodate the lower and upper bounds of the adjustment. If this is
  * not desired, the automatic sizing can be turned off by explicitly
- * setting #GtkSpinButton::width-chars to a value != -1.
+ * setting #GtkEditable::width-chars to a value != -1.
  *
  * ## Using a GtkSpinButton to get an integer
  *
diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c
index 36fa633f5a..8563ed4625 100644
--- a/gtk/gtkstylecontext.c
+++ b/gtk/gtkstylecontext.c
@@ -653,9 +653,8 @@ gtk_style_context_restore (GtkStyleContext *context)
  * @context: a #GtkStyleContext
  * @class_name: class name to use in styling
  *
- * Adds a style class to @context, so posterior calls to
- * gtk_style_context_get() or any of the gtk_render_*()
- * functions will make use of this new class for 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”
  * class, would be matched by:
@@ -866,9 +865,6 @@ gtk_style_context_lookup_color (GtkStyleContext *context,
  * @color: (out): return value for the foreground color
  *
  * Gets the foreground color for a given state.
- *
- * See gtk_style_context_get_property() and
- * #GTK_STYLE_PROPERTY_COLOR for details.
  **/
 void
 gtk_style_context_get_color (GtkStyleContext *context,
@@ -886,9 +882,6 @@ gtk_style_context_get_color (GtkStyleContext *context,
  * @border: (out): return value for the border settings
  *
  * Gets the border for a given state as a #GtkBorder.
- *
- * See gtk_style_context_get_property() and
- * #GTK_STYLE_PROPERTY_BORDER_WIDTH for details.
  **/
 void
 gtk_style_context_get_border (GtkStyleContext *context,
@@ -913,8 +906,6 @@ gtk_style_context_get_border (GtkStyleContext *context,
  * @padding: (out): return value for the padding settings
  *
  * Gets the padding for a given state as a #GtkBorder.
- * See gtk_style_context_get() and #GTK_STYLE_PROPERTY_PADDING
- * for details.
  **/
 void
 gtk_style_context_get_padding (GtkStyleContext *context,
@@ -939,8 +930,6 @@ gtk_style_context_get_padding (GtkStyleContext *context,
  * @margin: (out): return value for the margin settings
  *
  * Gets the margin for a given state as a #GtkBorder.
- * See gtk_style_property_get() and #GTK_STYLE_PROPERTY_MARGIN
- * for details.
  **/
 void
 gtk_style_context_get_margin (GtkStyleContext *context,
diff --git a/gtk/gtktextiter.c b/gtk/gtktextiter.c
index 6fdf42d138..abb316fd9c 100644
--- a/gtk/gtktextiter.c
+++ b/gtk/gtktextiter.c
@@ -1382,10 +1382,11 @@ gtk_text_iter_get_tags (const GtkTextIter *iter)
  * @default_setting: %TRUE if text is editable by default
  *
  * Returns whether the character at @iter is within an editable region
- * of text.  Non-editable text is “locked” and can’t be changed by the
- * user via #GtkTextView. This function is simply a convenience
- * wrapper around gtk_text_iter_get_attributes(). If no tags applied
- * to this text affect editability, @default_setting will be returned.
+ * of text.
+ *
+ * Non-editable text is “locked” and can’t be changed by the
+ * user via #GtkTextView. If no tags applied to this text affect
+ * editability, @default_setting will be returned.
  *
  * You don’t want to use this function to decide whether text can be
  * inserted at @iter, because for insertion you don’t want to know
@@ -1393,7 +1394,7 @@ gtk_text_iter_get_tags (const GtkTextIter *iter)
  * know whether a new character inserted at @iter would be inside an
  * editable range. Use gtk_text_iter_can_insert() to handle this
  * case.
- * 
+ *
  * Returns: whether @iter is inside an editable range
  **/
 gboolean
@@ -1488,10 +1489,10 @@ gtk_text_iter_get_attributes (const GtkTextIter  *iter,
  * gtk_text_iter_get_language:
  * @iter: an iterator
  *
- * A convenience wrapper around gtk_text_iter_get_attributes(),
- * which returns the language in effect at @iter. If no tags affecting
- * language apply to @iter, the return value is identical to that of
- * gtk_get_default_language().
+ * Returns the language in effect at @iter.
+ *
+ * If no tags affecting language apply to @iter, the return
+ * value is identical to that of gtk_get_default_language().
  *
  * Returns: (transfer full): language in effect at @iter
  **/
diff --git a/gtk/gtktextview.c b/gtk/gtktextview.c
index 5aef271df6..7a53f2d029 100644
--- a/gtk/gtktextview.c
+++ b/gtk/gtktextview.c
@@ -889,8 +889,6 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    * Note that this property is confusingly named. In CSS terms,
    * the value set here is padding, and it is applied in addition
    * to the padding from the theme.
-   *
-   * Don't confuse this property with #GtkWidget:margin-left.
    */
   g_object_class_install_property (gobject_class,
                                    PROP_LEFT_MARGIN,
@@ -909,8 +907,6 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    * Note that this property is confusingly named. In CSS terms,
    * the value set here is padding, and it is applied in addition
    * to the padding from the theme.
-   *
-   * Don't confuse this property with #GtkWidget:margin-right.
    */
   g_object_class_install_property (gobject_class,
                                    PROP_RIGHT_MARGIN,
@@ -9023,10 +9019,7 @@ text_window_get_height (GtkTextWindow *win)
  * @window_y: (out) (allow-none): window y coordinate return location or %NULL
  *
  * Converts coordinate (@buffer_x, @buffer_y) to coordinates for the window
- * @win, and stores the result in (@window_x, @window_y). 
- *
- * Note that you can’t convert coordinates for a nonexisting window (see 
- * gtk_text_view_set_border_window_size()).
+ * @win, and stores the result in (@window_x, @window_y).
  **/
 void
 gtk_text_view_buffer_to_window_coords (GtkTextView      *text_view,
@@ -9091,9 +9084,6 @@ gtk_text_view_buffer_to_window_coords (GtkTextView      *text_view,
  *
  * Converts coordinates on the window identified by @win to buffer
  * coordinates, storing the result in (@buffer_x,@buffer_y).
- *
- * Note that you can’t convert coordinates for a nonexisting window (see 
- * gtk_text_view_set_border_window_size()).
  **/
 void
 gtk_text_view_window_to_buffer_coords (GtkTextView      *text_view,
diff --git a/gtk/gtktextview.h b/gtk/gtktextview.h
index 1d929f040b..1c18d087b5 100644
--- a/gtk/gtktextview.h
+++ b/gtk/gtktextview.h
@@ -142,9 +142,7 @@ struct _GtkTextView
  *   view is drawing its own text. Applications can override this vfunc
  *   in a subclass to draw customized content underneath or above the
  *   text. In the %GTK_TEXT_VIEW_LAYER_BELOW_TEXT and %GTK_TEXT_VIEW_LAYER_ABOVE_TEXT
- *   the drawing is done in the buffer coordinate space, but the older (deprecated)
- *   layers %GTK_TEXT_VIEW_LAYER_BELOW and %GTK_TEXT_VIEW_LAYER_ABOVE work in viewport
- *   coordinates, which makes them unnecessarily hard to use.
+ *   layers the drawing is done in the buffer coordinate space.
  * @extend_selection: The class handler for the #GtkTextView::extend-selection signal.
  * @insert_emoji: The class handler for the #GtkTextView::insert-emoji signal.
  */
diff --git a/gtk/gtktogglebutton.c b/gtk/gtktogglebutton.c
index 66c65f9a6e..bb6a3e8adf 100644
--- a/gtk/gtktogglebutton.c
+++ b/gtk/gtktogglebutton.c
@@ -40,7 +40,7 @@
  * SECTION:gtktogglebutton
  * @Short_description: Create buttons which retain their state
  * @Title: GtkToggleButton
- * @See_also: #GtkButton, #GtkCheckButton, #GtkCheckMenuItem
+ * @See_also: #GtkButton, #GtkCheckButton
  *
  * A #GtkToggleButton is a #GtkButton which will remain “pressed-in” when
  * clicked. Clicking again will cause the toggle button to return to its
diff --git a/gtk/gtktooltip.c b/gtk/gtktooltip.c
index 284e96d912..e3011b4d6a 100644
--- a/gtk/gtktooltip.c
+++ b/gtk/gtktooltip.c
@@ -62,19 +62,6 @@
  *
  *   Return %TRUE from your query-tooltip handler. This causes the tooltip to be
  *   show. If you return %FALSE, it will not be shown.
- *
- * In the probably rare case where you want to have even more control over the
- * tooltip that is about to be shown, you can set your own #GtkWindow which
- * will be used as tooltip window.  This works as follows:
- * 
- * - Set #GtkWidget:has-tooltip and connect to #GtkWidget::query-tooltip as before.
- *   Use gtk_widget_set_tooltip_window() to set a #GtkWindow created by you as
- *   tooltip window.
- *
- * - In the #GtkWidget::query-tooltip callback you can access your window using
- *   gtk_widget_get_tooltip_window() and manipulate as you wish. The semantics of
- *   the return value are exactly as before, return %TRUE to show the window,
- *   %FALSE to not show it.
  */
 
 
@@ -357,7 +344,7 @@ gtk_tooltip_set_tip_area (GtkTooltip         *tooltip,
     }
 }
 
-/**
+/*
  * gtk_tooltip_trigger_tooltip_query:
  * @display: a #GdkDisplay
  *
diff --git a/gtk/gtktreelistmodel.c b/gtk/gtktreelistmodel.c
index 82b6bf5056..3857ad9ea6 100644
--- a/gtk/gtktreelistmodel.c
+++ b/gtk/gtktreelistmodel.c
@@ -819,7 +819,7 @@ gtk_tree_list_model_get_passthrough (GtkTreeListModel *self)
  *
  * If set to %TRUE, the model will recursively expand all rows that
  * get added to the model. This can be either rows added by changes
- * to the underlying models or via gtk_tree_list_model_set_expanded().
+ * to the underlying models or via gtk_tree_list_row_set_expanded().
  **/
 void
 gtk_tree_list_model_set_autoexpand (GtkTreeListModel *self,
@@ -841,7 +841,7 @@ gtk_tree_list_model_set_autoexpand (GtkTreeListModel *self,
  *
  * Gets whether the model is set to automatically expand new rows
  * that get added. This can be either rows added by changes to the
- * underlying models or via gtk_tree_list_model_set_expanded().
+ * underlying models or via gtk_tree_list_row_set_expanded().
  *
  * Returns: %TRUE if the model is set to autoexpand
  **/
diff --git a/gtk/gtktreemodel.c b/gtk/gtktreemodel.c
index 23495b44f3..28e7a73716 100644
--- a/gtk/gtktreemodel.c
+++ b/gtk/gtktreemodel.c
@@ -32,7 +32,7 @@
  * @Title: GtkTreeModel
  * @Short_description: The tree interface used by GtkTreeView
  * @See_also: #GtkTreeView, #GtkTreeStore, #GtkListStore,
- *     [GtkTreeView drag-and-drop][gtk3-GtkTreeView-drag-and-drop]
+ *     [GtkTreeView drag-and-drop][gtk4-GtkTreeView-drag-and-drop]
  *     #GtkTreeSortable
  *
  * The #GtkTreeModel interface defines a generic tree interface for
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index b76e46bb80..8f92c09a88 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -118,8 +118,9 @@
  * itself or its child widgets, the #GtkWidgetClass.get_request_mode()
  * virtual function must be implemented as well and return the widget's
  * preferred request mode. The default implementation of this virtual function
- * returns %GTK_SIZE_REQUEST_CONSTANT_SIZE, which means that the widget will only ever
- * get -1 passed as the for_size value to its #GtkWidgetClass.measure() implementation.
+ * returns %GTK_SIZE_REQUEST_CONSTANT_SIZE, which means that the widget will
+ * only ever get -1 passed as the for_size value to its #GtkWidgetClass.measure()
+ * implementation.
  *
  * The geometry management system will query a widget hierarchy in
  * only one orientation at a time. When widgets are initially queried
@@ -129,18 +130,17 @@
  * For example, when queried in the normal
  * %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH mode:
  * First, the default minimum and natural width for each widget
- * in the interface will be computed using gtk_widget_measure() with an orientation
- * of %GTK_ORIENTATION_HORIZONTAL and a for_size of -1.
+ * in the interface will be computed using gtk_widget_measure() with an
+ * orientation of %GTK_ORIENTATION_HORIZONTAL and a for_size of -1.
  * Because the preferred widths for each widget depend on the preferred
  * widths of their children, this information propagates up the hierarchy,
  * and finally a minimum and natural width is determined for the entire
  * toplevel. Next, the toplevel will use the minimum width to query for the
  * minimum height contextual to that width using gtk_widget_measure() with an
  * orientation of %GTK_ORIENTATION_VERTICAL and a for_size of the just computed
- * width. This will also be a highly recursive operation.
- * The minimum height for the minimum width is normally
- * used to set the minimum size constraint on the toplevel
- * (unless gtk_window_set_geometry_hints() is explicitly used instead).
+ * width. This will also be a highly recursive operation. The minimum height
+ * for the minimum width is normally used to set the minimum size constraint
+ * on the toplevel.
  *
  * After the toplevel window has initially requested its size in both
  * dimensions it can go on to allocate itself a reasonable size (or a size
@@ -5285,15 +5285,8 @@ gtk_widget_update_state_flags (GtkWidget     *widget,
  * values in the current widget state (insensitive, prelighted, etc.).
  *
  * This function accepts the values %GTK_STATE_FLAG_DIR_LTR and
- * %GTK_STATE_FLAG_DIR_RTL but ignores them. If you want to set the widget's
- * direction, use gtk_widget_set_direction().
- *
- * It is worth mentioning that any other state than %GTK_STATE_FLAG_INSENSITIVE,
- * will be propagated down to all non-internal children if @widget is a
- * #GtkContainer, while %GTK_STATE_FLAG_INSENSITIVE itself will be propagated
- * down to all #GtkContainer children by different means than turning on the
- * state flag down the hierarchy, both gtk_widget_get_state_flags() and
- * gtk_widget_is_sensitive() will make use of these.
+ * %GTK_STATE_FLAG_DIR_RTL but ignores them. If you want to set
+ * the widget's direction, use gtk_widget_set_direction().
  **/
 void
 gtk_widget_set_state_flags (GtkWidget     *widget,
@@ -6499,11 +6492,11 @@ gtk_widget_get_display (GtkWidget *widget)
  * gtk_widget_child_focus() is called by widgets as the user moves
  * around the window using keyboard shortcuts. @direction indicates
  * what kind of motion is taking place (up, down, left, right, tab
- * forward, tab backward). gtk_widget_child_focus() emits the
- * #GtkWidget::focus signal; widgets override the default handler
- * for this signal in order to implement appropriate focus behavior.
+ * forward, tab backward). gtk_widget_child_focus() calls the
+ * #GtkWidgetClass.focus() vfunc; widgets override this vfunc
+ * in order to implement appropriate focus behavior.
  *
- * The default ::focus handler for a widget should return %TRUE if
+ * The default focus() vfunc for a widget should return %TRUE if
  * moving in @direction left the focus on a focusable location inside
  * that widget, and %FALSE if moving in @direction moved the focus
  * outside the widget. If returning %TRUE, widgets normally
@@ -8992,9 +8985,8 @@ gtk_widget_remove_mnemonic_label (GtkWidget *widget,
  * gtk_widget_trigger_tooltip_query:
  * @widget: a #GtkWidget
  *
- * Triggers a tooltip query on the display where the toplevel of @widget
- * is located. See gtk_tooltip_trigger_tooltip_query() for more
- * information.
+ * Triggers a tooltip query on the display where the toplevel
+ * of @widget is located.
  */
 void
 gtk_widget_trigger_tooltip_query (GtkWidget *widget)
@@ -9214,17 +9206,19 @@ gtk_widget_get_has_tooltip (GtkWidget *widget)
  *
  * Retrieves the widget’s allocation.
  *
- * Note, when implementing a #GtkContainer: a widget’s allocation will
- * be its “adjusted” allocation, that is, the widget’s parent
- * container typically calls gtk_widget_size_allocate() with an
- * allocation, and that allocation is then adjusted (to handle margin
+ * Note, when implementing a layout container: a widget’s allocation
+ * will be its “adjusted” allocation, that is, the widget’s parent
+ * typically calls gtk_widget_size_allocate() with an allocation,
+ * and that allocation is then adjusted (to handle margin
  * and alignment for example) before assignment to the widget.
  * gtk_widget_get_allocation() returns the adjusted allocation that
  * was actually assigned to the widget. The adjusted allocation is
  * guaranteed to be completely contained within the
- * gtk_widget_size_allocate() allocation, however. So a #GtkContainer
- * is guaranteed that its children stay inside the assigned bounds,
- * but not that they have exactly the bounds the container assigned.
+ * gtk_widget_size_allocate() allocation, however.
+ *
+ * So a layout container is guaranteed that its children stay inside
+ * the assigned bounds, but not that they have exactly the bounds the
+ * container assigned.
  */
 void
 gtk_widget_get_allocation (GtkWidget     *widget,
@@ -9588,7 +9582,7 @@ gtk_widget_get_allocated_height (GtkWidget *widget)
  * Returns the baseline that has currently been allocated to @widget.
  * This function is intended to be used when implementing handlers
  * for the #GtkWidgetClass.snapshot() function, and when allocating child
- * widgets in #GtkWidget::size_allocate.
+ * widgets in #GtkWidgetClass.size_allocate().
  *
  * Returns: the baseline of the @widget, or -1 if none
  **/
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 984e766be0..066b1dd873 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -106,24 +106,6 @@
  *
  * # GtkWindow as GtkBuildable
  *
- * The GtkWindow implementation of the #GtkBuildable interface supports a
- * custom <accel-groups> element, which supports any number of <group>
- * elements representing the #GtkAccelGroup objects you want to add to
- * your window (synonymous with gtk_window_add_accel_group().
- *
- * An example of a UI definition fragment with accel groups:
- * |[
- * <object class="GtkWindow">
- *   <accel-groups>
- *     <group name="accelgroup1"/>
- *   </accel-groups>
- * </object>
- * 
- * ...
- * 
- * <object class="GtkAccelGroup" id="accelgroup1"/>
- * ]|
- * 
  * The GtkWindow implementation of the #GtkBuildable interface supports
  * setting a child as the titlebar by specifying “titlebar” as the “type”
  * attribute of a <child> element.
@@ -2122,8 +2104,9 @@ gtk_window_set_default_widget (GtkWindow *window,
  * gtk_window_get_default_widget:
  * @window: a #GtkWindow
  *
- * Returns the default widget for @window. See
- * gtk_window_set_default() for more details.
+ * Returns the default widget for @window.
+ *
+ * See gtk_window_set_default_widget() for more details.
  *
  * Returns: (nullable) (transfer none): the default widget, or %NULL
  * if there is none.
@@ -3252,9 +3235,8 @@ gtk_window_get_icon_name (GtkWindow *window)
  * gtk_window_set_default_icon_name:
  * @name: the name of the themed icon
  *
- * Sets an icon to be used as fallback for windows that haven't
- * had gtk_window_set_icon_list() called on them from a named
- * themed icon, see gtk_window_set_icon_name().
+ * Sets an icon to be used as fallback for windows that
+ * haven't had gtk_window_set_icon_name() called on them.
  **/
 void
 gtk_window_set_default_icon_name (const char *name)
@@ -3588,20 +3570,6 @@ gtk_window_resize (GtkWindow *window,
  *   // ...
  * }
  * ]|
- *
- * If you are getting a window size in order to position the window
- * on the screen, don't. You should, instead, simply let the window
- * manager place windows. Also, if you set the transient parent of
- * dialogs with gtk_window_set_transient_for() window managers will
- * often center the dialog over its parent window. It's much preferred
- * to let the window manager handle these cases rather than doing it
- * yourself, because all apps will behave consistently and according to
- * user or system preferences, if the window manager handles it. Also,
- * the window manager can take into account the size of the window
- * decorations and border that it may add, and of which GTK+ has no
- * knowledge. Additionally, positioning windows in global screen coordinates
- * may not be allowed by the windowing system. For more information,
- * see: gtk_window_set_position().
  */
 void
 gtk_window_get_size (GtkWindow *window,
@@ -6342,11 +6310,12 @@ _gtk_window_set_is_active (GtkWindow *window,
  * gtk_window_set_auto_startup_notification:
  * @setting: %TRUE to automatically do startup notification
  *
- * By default, after showing the first #GtkWindow, GTK+ calls 
- * gdk_notify_startup_complete().  Call this function to disable 
- * the automatic startup notification. You might do this if your 
- * first window is a splash screen, and you want to delay notification 
- * until after your real main window has been shown, for example.
+ * By default, after showing the first #GtkWindow, GTK calls
+ * gdk_display_notify_startup_complete(). Call this function to
+ * disable the automatic startup notification. You might do this
+ * if your first window is a splash screen, and you want to delay
+ * notification until after your real main window has been shown,
+ * for example.
  *
  * In that example, you would disable startup notification
  * temporarily, show your splash screen, then re-enable it so that