diff --git a/gtk/gtkcheckbutton.c b/gtk/gtkcheckbutton.c
index a3d02f9ee5..ab7a862779 100644
--- a/gtk/gtkcheckbutton.c
+++ b/gtk/gtkcheckbutton.c
@@ -802,7 +802,13 @@ gtk_check_button_set_label (GtkCheckButton *self,
  * Setting the group of a check button also changes the css name of the
  * indicator widget's CSS node to 'radio'.
  *
- * The behavior of a checkbutton in a group is also commonly known as a 'radio button'.
+ * The behavior of a checkbutton in a group is also commonly known as
+ * a 'radio button'.
+ *
+ * Note that the same effect can be achieved via the #GtkActionable
+ * api, by using the same action with parameter type and state type 's'
+ * for all buttons in the group, and giving each button its own target
+ * value.
  */
 void
 gtk_check_button_set_group (GtkCheckButton *self,
diff --git a/gtk/gtktogglebutton.c b/gtk/gtktogglebutton.c
index edce7e0368..45019471b7 100644
--- a/gtk/gtktogglebutton.c
+++ b/gtk/gtktogglebutton.c
@@ -446,6 +446,12 @@ gtk_toggle_button_toggled (GtkToggleButton *toggle_button)
  *
  * Adds @self to the group of @group. In a group of multiple toggle buttons,
  * only one button can be active at a time.
+ *
+ * Note that the same effect can be achieved via the #GtkActionable
+ * api, by using the same action with parameter type and state type 's'
+ * for all buttons in the group, and giving each button its own target
+ * value.
+
  */
 void
 gtk_toggle_button_set_group (GtkToggleButton *self,