[gtk/docs-work: 4/4] Docs: Various tweaks

[Matthias Clasen <matthiasc src gnome org>]

commit e91907d427b6eb4ee659bbd57376cff769aca1ee
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun Apr 19 16:26:25 2020 -0400

    Docs: Various tweaks
    
    Tweak the docs for library initialization, versioning
    and settings, and remove some outdated information.

 gtk/gtkmain.c       | 41 ++++++++++++++++++++---------------------
 gtk/gtksettings.c   | 21 +++++++++++----------
 gtk/gtkversion.h.in |  4 ++--
 3 files changed, 33 insertions(+), 33 deletions(-)
---
diff --git a/gtk/gtkmain.c b/gtk/gtkmain.c
index cbb09c802c..7951dceaf5 100644
--- a/gtk/gtkmain.c
+++ b/gtk/gtkmain.c
@@ -24,29 +24,28 @@
 
 /**
  * SECTION:gtkmain
- * @Short_description: Library initialization, main event loop, and events
- * @Title: Main loop and Events
- * @See_also:See the GLib manual, especially #GMainLoop and signal-related
+ * @Short_description: Library initialization and main loop
+ * @Title: Initialization
+ * @See_also: See the GLib manual, especially #GMainLoop and signal-related
  *    functions such as g_signal_connect()
  *
- * Before using GTK, you need to initialize it; initialization connects to the
- * window system display, and parses some standard command line arguments. The
- * gtk_init() macro initializes GTK. gtk_init() exits the application if errors
- * occur; to avoid this, use gtk_init_check(). gtk_init_check() allows you to
- * recover from a failed GTK initialization - you might start up your
- * application in text mode instead.
+ * Before using GTK, you need to initialize it using gtk_init(); this
+ * connects to the windowing system, sets up the locale and performs other
+ * initialization tasks. gtk_init() exits the application if errors occur;
+ * to avoid this, you can use gtk_init_check(), which allows you to recover
+ * from a failed GTK initialization - you might start up your application
+ * in text mode instead.
  *
  * Like all GUI toolkits, GTK uses an event-driven programming model. When the
- * user is doing nothing, GTK sits in the “main loop” and
- * waits for input. If the user performs some action - say, a mouse click - then
- * the main loop “wakes up” and delivers an event to GTK. GTK forwards the
- * event to one or more widgets.
+ * user is doing nothing, GTK sits in the “main loop” and waits for input.
+ * If the user performs some action - say, a mouse click - then the main loop
+ * “wakes up” and delivers an event to GTK. GTK forwards the event to one or
+ * more widgets.
  *
- * When widgets receive an event, they frequently emit one or more
- * “signals”. Signals notify your program that "something
- * interesting happened" by invoking functions you’ve connected to the signal
- * with g_signal_connect(). Functions connected to a signal are often termed
- * “callbacks”.
+ * When widgets receive an event, they frequently emit one or more “signals”.
+ * Signals notify your program that "something interesting happened" by invoking
+ * functions you’ve connected to the signal with g_signal_connect(). Functions
+ * connected to a signal are often called “callbacks”.
  *
  * When your callbacks are invoked, you would typically take some action - for
  * example, when an Open button is clicked you might display a
@@ -59,7 +58,7 @@
  * int
  * main (int argc, char **argv)
  * {
- *  GtkWidget *mainwin;
+ *  GtkWidget *window;
  *   // Initialize i18n support with bindtextdomain(), etc.
  *
  *   // ...
@@ -68,14 +67,14 @@
  *   gtk_init ();
  *
  *   // Create the main window
- *   mainwin = gtk_window_new ();
+ *   window = gtk_window_new ();
  *
  *   // Set up our GUI elements
  *
  *   // ...
  *
  *   // Show the application window
- *   gtk_widget_show (mainwin);
+ *   gtk_widget_show (window);
  *
  *   // Enter the main event loop, and wait for user interaction
  *   while (!done)
diff --git a/gtk/gtksettings.c b/gtk/gtksettings.c
index 6ce91b34b1..c6b9634213 100644
--- a/gtk/gtksettings.c
+++ b/gtk/gtksettings.c
@@ -74,14 +74,16 @@
  * On the X window system, this sharing is realized by an
  * [XSettings](http://www.freedesktop.org/wiki/Specifications/xsettings-spec)
  * manager that is usually part of the desktop environment, along with
- * utilities that let the user change these settings. In the absence of
- * an Xsettings manager, GTK reads default values for settings from
- * `settings.ini` files in
- * `/etc/gtk-4.0`, `$XDG_CONFIG_DIRS/gtk-4.0`
- * and `$XDG_CONFIG_HOME/gtk-4.0`.
- * These files must be valid key files (see #GKeyFile), and have
- * a section called Settings. Themes can also provide default values
- * for settings by installing a `settings.ini` file
+ * utilities that let the user change these settings.
+ *
+ * On Wayland, the settings are obtained either via a settings portal,
+ * or by reading desktop settings from DConf.
+ *
+ * In the absence of these sharing mechanisms, GTK reads default values for
+ * settings from `settings.ini` files in `/etc/gtk-4.0`, `$XDG_CONFIG_DIRS/gtk-4.0`
+ * and `$XDG_CONFIG_HOME/gtk-4.0`. These files must be valid key files (see
+ * #GKeyFile), and have a section called Settings. Themes can also provide
+ * default values for settings by installing a `settings.ini` file
  * next to their `gtk.css` file.
  *
  * Applications can override system-wide settings by setting the property
@@ -91,8 +93,7 @@
  *
  * There is one GtkSettings instance per display. It can be obtained with
  * gtk_settings_get_for_display(), but in many cases, it is more convenient
- * to use gtk_widget_get_settings(). gtk_settings_get_default() returns the
- * GtkSettings instance for the default display.
+ * to use gtk_widget_get_settings().
  */
 
 
diff --git a/gtk/gtkversion.h.in b/gtk/gtkversion.h.in
index b6b5337223..bccb24d144 100644
--- a/gtk/gtkversion.h.in
+++ b/gtk/gtkversion.h.in
@@ -31,10 +31,10 @@
 
 /**
  * SECTION:gtkfeatures
- * @Short_description: Variables and functions to check the GTK+ version
+ * @Short_description: Variables and functions to check the GTK version
  * @Title: Version Information
  *
- * GTK+ provides version information, primarily useful in configure checks
+ * GTK provides version information, primarily useful in configure checks
  * for builds that have a configure script. Applications will not typically
  * use the features described here.
  */