[tepl] Panel: polish

[Sébastien Wilmet <swilmet src gnome org>]

commit d49478a75fa2c20244deb030915d272b94277118
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Tue Apr 21 20:12:59 2020 +0200

    Panel: polish

 docs/reference/tepl-sections.txt |  6 +++---
 tepl/tepl-panel.c                | 34 ++++++++++++++++++++++------------
 tepl/tepl-panel.h                | 28 ++++++++++++++--------------
 3 files changed, 39 insertions(+), 29 deletions(-)
---
diff --git a/docs/reference/tepl-sections.txt b/docs/reference/tepl-sections.txt
index f33a460..ce90365 100644
--- a/docs/reference/tepl-sections.txt
+++ b/docs/reference/tepl-sections.txt
@@ -325,9 +325,9 @@ tepl_panel_new
 tepl_panel_new_for_left_side_panel
 tepl_panel_get_stack
 tepl_panel_add_component
-tepl_panel_set_active_component_setting
-tepl_panel_restore_settings
-tepl_panel_save_settings
+tepl_panel_provide_active_component_gsetting
+tepl_panel_restore_state_from_gsettings
+tepl_panel_save_state_to_gsettings
 <SUBSECTION Standard>
 TEPL_IS_PANEL
 TEPL_IS_PANEL_CLASS
diff --git a/tepl/tepl-panel.c b/tepl/tepl-panel.c
index 9795287..3185115 100644
--- a/tepl/tepl-panel.c
+++ b/tepl/tepl-panel.c
@@ -25,9 +25,13 @@
 /**
  * SECTION:panel
  * @Title: TeplPanel
- * @Short_description: Side or bottom panel
+ * @Short_description: Side or bottom panel container
  *
- * #TeplPanel permits to create a side or bottom panel with several components.
+ * #TeplPanel permits to create a side or bottom panel that contains several
+ * components.
+ *
+ * #TeplPanel is a #GtkGrid subclass containing only one child #GtkWidget by
+ * default: the #GtkStack that can be retrieved with tepl_panel_get_stack().
  */
 
 struct _TeplPanelPrivate
@@ -167,7 +171,8 @@ tepl_panel_new_for_left_side_panel (void)
  * tepl_panel_get_stack:
  * @panel: a #TeplPanel.
  *
- * Returns: (transfer none): the #GtkStack widget of @panel.
+ * Returns: (transfer none): the #GtkStack widget of @panel (a direct child
+ * #GtkWidget of @panel).
  * Since: 5.0
  */
 GtkStack *
@@ -215,7 +220,7 @@ tepl_panel_add_component (TeplPanel   *panel,
 }
 
 /**
- * tepl_panel_set_active_component_setting:
+ * tepl_panel_provide_active_component_gsetting:
  * @panel: a #TeplPanel.
  * @settings: a #GSettings object.
  * @setting_key: a #GSettings key of type string.
@@ -224,14 +229,19 @@ tepl_panel_add_component (TeplPanel   *panel,
  * #GtkStack:visible-child-name property of the #GtkStack belonging to @panel.
  *
  * This function just stores @settings and @setting_key for further use by
- * tepl_panel_restore_settings() and tepl_panel_save_settings().
+ * tepl_panel_restore_state_from_gsettings() and
+ * tepl_panel_save_state_to_gsettings().
+ *
+ * Note that only one @settings/@setting_key pair is stored by @panel for
+ * further use, if you call this function twice on the same @panel, the second
+ * call overrides the first one.
  *
  * Since: 5.0
  */
 void
-tepl_panel_set_active_component_setting (TeplPanel   *panel,
-                                        GSettings   *settings,
-                                        const gchar *setting_key)
+tepl_panel_provide_active_component_gsetting (TeplPanel   *panel,
+                                             GSettings   *settings,
+                                             const gchar *setting_key)
 {
        g_return_if_fail (TEPL_IS_PANEL (panel));
        g_return_if_fail (G_IS_SETTINGS (settings));
@@ -244,7 +254,7 @@ tepl_panel_set_active_component_setting (TeplPanel   *panel,
 }
 
 /**
- * tepl_panel_restore_settings:
+ * tepl_panel_restore_state_from_gsettings:
  * @panel: a #TeplPanel.
  *
  * Restores the state of @panel according to the provided #GSettings.
@@ -255,7 +265,7 @@ tepl_panel_set_active_component_setting (TeplPanel   *panel,
  * Since: 5.0
  */
 void
-tepl_panel_restore_settings (TeplPanel *panel)
+tepl_panel_restore_state_from_gsettings (TeplPanel *panel)
 {
        gchar *active_component_name;
        GtkWidget *child_widget;
@@ -286,7 +296,7 @@ tepl_panel_restore_settings (TeplPanel *panel)
 }
 
 /**
- * tepl_panel_save_settings:
+ * tepl_panel_save_state_to_gsettings:
  * @panel: a #TeplPanel.
  *
  * Saves the current state of @panel to the provided #GSettings.
@@ -294,7 +304,7 @@ tepl_panel_restore_settings (TeplPanel *panel)
  * Since: 5.0
  */
 void
-tepl_panel_save_settings (TeplPanel *panel)
+tepl_panel_save_state_to_gsettings (TeplPanel *panel)
 {
        const gchar *visible_child_name;
 
diff --git a/tepl/tepl-panel.h b/tepl/tepl-panel.h
index bae07db..21a9dcf 100644
--- a/tepl/tepl-panel.h
+++ b/tepl/tepl-panel.h
@@ -53,27 +53,27 @@ struct _TeplPanelClass
        gpointer padding[12];
 };
 
-GType          tepl_panel_get_type                     (void);
+GType          tepl_panel_get_type                             (void);
 
-TeplPanel *    tepl_panel_new                          (void);
+TeplPanel *    tepl_panel_new                                  (void);
 
-TeplPanel *    tepl_panel_new_for_left_side_panel      (void);
+TeplPanel *    tepl_panel_new_for_left_side_panel              (void);
 
-GtkStack *     tepl_panel_get_stack                    (TeplPanel *panel);
+GtkStack *     tepl_panel_get_stack                            (TeplPanel *panel);
 
-void           tepl_panel_add_component                (TeplPanel   *panel,
-                                                        GtkWidget   *component,
-                                                        const gchar *name,
-                                                        const gchar *title,
-                                                        const gchar *icon_name);
+void           tepl_panel_add_component                        (TeplPanel   *panel,
+                                                                GtkWidget   *component,
+                                                                const gchar *name,
+                                                                const gchar *title,
+                                                                const gchar *icon_name);
 
-void           tepl_panel_set_active_component_setting (TeplPanel   *panel,
-                                                        GSettings   *settings,
-                                                        const gchar *setting_key);
+void           tepl_panel_provide_active_component_gsetting    (TeplPanel   *panel,
+                                                                GSettings   *settings,
+                                                                const gchar *setting_key);
 
-void           tepl_panel_restore_settings             (TeplPanel *panel);
+void           tepl_panel_restore_state_from_gsettings         (TeplPanel *panel);
 
-void           tepl_panel_save_settings                (TeplPanel *panel);
+void           tepl_panel_save_state_to_gsettings              (TeplPanel *panel);
 
 G_END_DECLS