[gtk/action-muxer-speedup: 19/19] actionmuxer: Update docs and clean up headers

[Matthias Clasen <matthiasc src gnome org>]

commit 486fbce42bdac6803390abb76a8753929a07ea64
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun Jul 19 17:04:11 2020 -0400

    actionmuxer: Update docs and clean up headers
    
    Update the doc comment at the top to describe the
    current  functionality of GtkActionMuxer.

 gtk/gtkactionmuxer.c        | 30 ++++++++++++++++++++++--------
 gtk/gtkactionmuxerprivate.h | 44 ++++++++++++++++++++------------------------
 2 files changed, 42 insertions(+), 32 deletions(-)
---
diff --git a/gtk/gtkactionmuxer.c b/gtk/gtkactionmuxer.c
index 3c013507cb..31800680c2 100644
--- a/gtk/gtkactionmuxer.c
+++ b/gtk/gtkactionmuxer.c
@@ -105,10 +105,24 @@ gtk_accels_remove (GtkAccels  *accels,
 
 /*< private >
  * SECTION:gtkactionmuxer
- * @short_description: Aggregate and monitor several action groups
+ * @short_description: Aggregate and monitor actions from multiple sources
  *
- * #GtkActionMuxer is a #GActionGroup and #GtkActionObservable that is
- * capable of containing other #GActionGroup instances.
+ * #GtkActionMuxer is #GtkActionObservable and #GtkActionObserver that
+ * offers a #GActionGroup-like api and is capable of containing other
+ * #GActionGroup instances. #GtkActionMuxer does not implement the
+ * #GActionGroup interface because it requires excessive signal emissions
+ * and has poor scalability. We use the #GtkActionObserver machinery
+ * instead to propagate changes between action muxer instances and
+ * to other users.
+ *
+ * Beyond action groups, #GtkActionMuxer can incorporate actions that
+ * are associated with widget classes (*class actions*) and actions
+ * that are associated with the parent widget, allowing for recursive
+ * lookup.
+ *
+ * In addition to the action attributes provided by #GActionGroup,
+ * #GtkActionMuxer maintains a *primary accelerator* string for
+ * actions that can be shown in menuitems.
  *
  * The typical use is aggregating all of the actions applicable to a
  * particular context into a single action group, with namespacing.
@@ -119,12 +133,12 @@ gtk_accels_remove (GtkAccels  *accels,
  * application (such as “fullscreen”).
  *
  * In this case, each of these action groups could be added to a
- * #GtkActionMuxer with the prefixes “app” and “win”, respectively.  This
- * would expose the actions as “app.quit” and “win.fullscreen” on the
- * #GActionGroup interface presented by the #GtkActionMuxer.
+ * #GtkActionMuxer with the prefixes “app” and “win”, respectively.
+ * This would expose the actions as “app.quit” and “win.fullscreen”
+ * on the #GActionGroup-like interface presented by the #GtkActionMuxer.
  *
- * Activations and state change requests on the #GtkActionMuxer are wired
- * through to the underlying action group in the expected way.
+ * Activations and state change requests on the #GtkActionMuxer are
+ * wired through to the underlying actions in the expected way.
  *
  * This class is typically only used at the site of “consumption” of
  * actions (eg: when displaying a menu that contains many actions on
diff --git a/gtk/gtkactionmuxerprivate.h b/gtk/gtkactionmuxerprivate.h
index 7708d5eb1c..19e3365672 100644
--- a/gtk/gtkactionmuxerprivate.h
+++ b/gtk/gtkactionmuxerprivate.h
@@ -52,7 +52,7 @@ GType                   gtk_action_muxer_get_type                       (void);
 GtkActionMuxer *        gtk_action_muxer_new                            (GtkWidget      *widget);
 
 void                    gtk_action_muxer_insert                         (GtkActionMuxer *muxer,
-                                                                         const gchar    *prefix,
+                                                                         const char     *prefix,
                                                                          GActionGroup   *action_group);
 
 void                    gtk_action_muxer_remove                         (GtkActionMuxer *muxer,
@@ -65,13 +65,7 @@ GtkActionMuxer *        gtk_action_muxer_get_parent                     (GtkActi
 void                    gtk_action_muxer_set_parent                     (GtkActionMuxer *muxer,
                                                                          GtkActionMuxer *parent);
 
-void                    gtk_action_muxer_set_primary_accel              (GtkActionMuxer *muxer,
-                                                                         const gchar    *action_and_target,
-                                                                         const gchar    *primary_accel);
-
-const char *            gtk_action_muxer_get_primary_accel              (GtkActionMuxer *muxer,
-                                                                         const gchar    *action_and_target);
-
+/* GActionGroup equivalent api */
 gboolean                gtk_action_muxer_query_action                   (GtkActionMuxer      *muxer,
                                                                          const char          *action_name,
                                                                          gboolean            *enabled,
@@ -89,25 +83,27 @@ gboolean                gtk_action_muxer_has_action                     (GtkActi
                                                                          const char          *action_name);
 char **                 gtk_action_muxer_list_actions                   (GtkActionMuxer      *muxer);
 
+/* api for class actions */
+void                    gtk_action_muxer_action_enabled_changed         (GtkActionMuxer      *muxer,
+                                                                         const char          *action_name,
+                                                                         gboolean             enabled);
+void                    gtk_action_muxer_action_state_changed           (GtkActionMuxer      *muxer,
+                                                                         const char          *action_name,
+                                                                         GVariant            *state);
+void                    gtk_action_muxer_connect_class_actions          (GtkActionMuxer      *muxer);
 
-void
-gtk_action_muxer_action_enabled_changed (GtkActionMuxer *muxer,
-                                         const char     *action_name,
-                                         gboolean        enabled);
-void
-gtk_action_muxer_action_state_changed (GtkActionMuxer *muxer,
-                                       const gchar    *action_name,
-                                       GVariant       *state);
-
-
-void gtk_action_muxer_connect_class_actions (GtkActionMuxer *muxer);
+/* api for accels */
+void                    gtk_action_muxer_set_primary_accel              (GtkActionMuxer      *muxer,
+                                                                         const char          
*action_and_target,
+                                                                         const char          *primary_accel);
+const char *            gtk_action_muxer_get_primary_accel              (GtkActionMuxer      *muxer,
+                                                                         const char          
*action_and_target);
 
 /* No better place for these... */
-gchar *                 gtk_print_action_and_target                     (const gchar    *action_namespace,
-                                                                         const gchar    *action_name,
-                                                                         GVariant       *target);
-
-gchar *                 gtk_normalise_detailed_action_name              (const gchar *detailed_action_name);
+char *                  gtk_print_action_and_target                     (const char          
*action_namespace,
+                                                                         const char          *action_name,
+                                                                         GVariant            *target);
+char *                  gtk_normalise_detailed_action_name              (const char          
*detailed_action_name);
 
 G_END_DECLS