[libadwaita/wip/exalm/docs: 1/4] view-switcher: Clarify docs

[Alexander Mikhaylenko <alexm src gnome org>]

commit 42baaa85adce5ea2f64a7a40ea4ed6a579a126bf
Author: Alexander Mikhaylenko <alexm gnome org>
Date:   Fri Dec 24 16:03:53 2021 +0500

    view-switcher: Clarify docs

 src/adw-view-switcher-bar.c   | 11 ++++++-----
 src/adw-view-switcher-title.c | 15 ++++++++++-----
 src/adw-view-switcher.c       | 10 ++++++----
 3 files changed, 22 insertions(+), 14 deletions(-)
---
diff --git a/src/adw-view-switcher-bar.c b/src/adw-view-switcher-bar.c
index 75fcbfeb..88479e78 100644
--- a/src/adw-view-switcher-bar.c
+++ b/src/adw-view-switcher-bar.c
@@ -26,12 +26,13 @@
  * at the bottom of a window and to be revealed only on really narrow windows,
  * e.g. on mobile phones. It can't be revealed if there are less than two pages.
  *
- * You can conveniently bind the [property@Adw.ViewSwitcherBar:reveal] property
- * to [property@Adw.ViewSwitcherTitle:title-visible] to automatically reveal the
- * view switcher bar when the title label is displayed in place of the view
- * switcher.
+ * `Adw.ViewSwitcherBar` is intended to be used together with
+ * [class@Adw.ViewSwitcherTitle].
  *
- * An example of the UI definition for a common use case:
+ * A common use case is to bind the [property@Adw.ViewSwitcherBar:reveal]
+ * property to [property@Adw.ViewSwitcherTitle:title-visible] to automatically
+ * reveal the view switcher bar when the title label is displayed in place of
+ * the view switcher, as follows:
  *
  * ```xml
  * <object class="GtkWindow">
diff --git a/src/adw-view-switcher-title.c b/src/adw-view-switcher-title.c
index 75c39d5f..b3cfa0dc 100644
--- a/src/adw-view-switcher-title.c
+++ b/src/adw-view-switcher-title.c
@@ -29,12 +29,17 @@
  * will display the window's title when the window is too narrow to fit the view
  * switcher e.g. on mobile phones, or if there are less than two views.
  *
- * You can conveniently bind the [property@Adw.ViewSwitcherBar:reveal] property
- * to [property@Adw.ViewSwitcherTitle:title-visible] to automatically reveal the
- * view switcher bar when the title label is displayed in place of the view
- * switcher.
+ * In order to center the title in narrow windows, the header bar should have
+ * [property@Adw.HeaderBar:centering-policy] set to
+ * `ADW_CENTERING_POLICY_STRICT`.
  *
- * An example of the UI definition for a common use case:
+ * `Adw.ViewSwitcherTitle` is intended to be used together with
+ * [class@Adw.ViewSwitcherBar].
+ *
+ * A common use case is to bind the [property@Adw.ViewSwitcherBar:reveal]
+ * property to [property@Adw.ViewSwitcherTitle:title-visible] to automatically
+ * reveal the view switcher bar when the title label is displayed in place of
+ * the view switcher, as follows:
  *
  * ```xml
  * <object class="GtkWindow">
diff --git a/src/adw-view-switcher.c b/src/adw-view-switcher.c
index df6200a3..071f4484 100644
--- a/src/adw-view-switcher.c
+++ b/src/adw-view-switcher.c
@@ -29,10 +29,12 @@
  * contained in a [class@Adw.ViewStack] in a similar fashion to
  * [class@Gtk.StackSwitcher].
  *
- * Depending on the available width, the view switcher can adapt from a wide
- * mode showing the view's icon and title side by side, to a narrow mode showing
- * the view's icon and title one on top of the other, in a more compact way.
- * This can be controlled via the [property@Adw.ViewSwitcher:policy] property.
+ * `AdwViewSwitcher` buttons always have an icon and a label. They can be
+ * displayed side by side, or icon on top of the label. This can be controlled
+ * via the [property@Adw.ViewSwitcher:policy] property.
+ *
+ * Most applications should be using [class@Adw.ViewSwitcherBar] and
+ * [class@Adw.ViewSwitcherTitle].
  *
  * ## CSS nodes
  *