- * Each action can have one or more proxy menu item, toolbar button or
- * other proxy widgets. Proxies mirror the state of the action (text
- * label, tooltip, icon, visible, sensitive, etc), and should change when
- * the action's state changes. When the proxy is activated, it should
- * activate its action.
+ * Each action can have one or more proxy widgets. To act as an action proxy,
+ * widget needs to implement #GtkActivatable interface. Proxies mirror the state
+ * of the action and should change when the action's state changes. Properties
+ * that are always mirrored by proxies are #GtkAction:sensitive and
+ * #GtkAction:visible. #GtkAction:gicon, #GtkAction:icon-name, #GtkAction:label,
+ * #GtkAction:short-label and #GtkAction:stock-id properties are only mirorred
+ * if proxy widget has #GtkActivatable:use-action-appearance property set to
+ * %TRUE.
+ *
+ * When the proxy is activated, it should activate its action.