Merge branch 'doc-improvements' into 'main'

Two docs improvements

See merge request GNOME/gtk!5406

2 files changed, 8 insertions, 22 deletions

diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 497554355a..dfe4a6dbb0 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -5664,10 +5664,6 @@ gtk_widget_get_state_flags (GtkWidget *widget)
  *
  * Note that setting this to %TRUE doesn’t mean the widget is
  * actually viewable, see [method@Gtk.Widget.get_visible].
- *
- * This function simply calls [method@Gtk.Widget.show] or
- * [method@Gtk.Widget.hide] but is nicer to use when the
- * visibility of the widget depends on some condition.
  */
 void
 gtk_widget_set_visible (GtkWidget *widget,
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 909154c231..88cc0b71ab 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -5206,9 +5206,12 @@ _gtk_window_unset_focus_and_default (GtkWindow *window,
  *
  * Presents a window to the user.
  *
- * This function should not be used as when it is called,
- * it is too late to gather a valid timestamp to allow focus
- * stealing prevention to work correctly.
+ * This may mean raising the window in the stacking order,
+ * unminimizing it, moving it to the current desktop and/or
+ * giving it the keyboard focus (possibly dependent on the user’s
+ * platform, window manager and preferences).
+ *
+ * If @window is hidden, this function also makes it visible.
  */
 void
 gtk_window_present (GtkWindow *window)
@@ -5222,23 +5225,10 @@ gtk_window_present (GtkWindow *window)
  * @timestamp: the timestamp of the user interaction (typically a
  *   button or key press event) which triggered this call
  *
- * Presents a window to the user.
- *
- * This may mean raising the window in the stacking order,
- * unminimizing it, moving it to the current desktop, and/or
- * giving it the keyboard focus, possibly dependent on the user’s
- * platform, window manager, and preferences.
- *
- * If @window is hidden, this function calls [method@Gtk.Widget.show]
- * as well.
+ * Presents a window to the user in response to an user interaction.
  *
- * This function should be used when the user tries to open a window
- * that’s already open. Say for example the preferences dialog is
- * currently open, and the user chooses Preferences from the menu
- * a second time; use [method@Gtk.Window.present] to move the
- * already-open dialog where the user can see it.
+ * See [method@Gtk.Window.present] for more details.
  *
- * Presents a window to the user in response to a user interaction.
  * The timestamp should be gathered when the window was requested
  * to be shown (when clicking a link for example), rather than once
  * the window is ready to be shown.