[gtk/ebassi/password-entry-notify] docs: Note the caveat on GtkEditable signals with delegates

[Emmanuele Bassi <ebassi src gnome org>]

commit e71f6b0bc073584015e9bd5ea77ad9557ff61be8
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Thu Dec 17 15:13:43 2020 +0000

    docs: Note the caveat on GtkEditable signals with delegates
    
    We cannot bubble up ::insert-text and ::delete-text signals from the
    delegate to the wrapper editable without causing an infinite recursion,
    due to how the signals are designed; ideally, we would have decoupled
    signal emission from virtual functions *before* releasing GTK4, but now
    that we have, we can't break the contract.

 gtk/gtkeditable.c | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)
---
diff --git a/gtk/gtkeditable.c b/gtk/gtkeditable.c
index eae161c542..48ae98dd20 100644
--- a/gtk/gtkeditable.c
+++ b/gtk/gtkeditable.c
@@ -133,8 +133,8 @@
  * }
  * ]|
  * 
- * Finally, use gtk_editable_delegate_set_property() in your set_property
- * function (and similar for get_property), to set the editable properties:
+ * Finally, use gtk_editable_delegate_set_property() in your `set_property`
+ * function (and similar for `get_property`), to set the editable properties:
  *
  * |[
  *   ...
@@ -144,6 +144,14 @@
  *   switch (prop_id)
  *   ...
  * ]|
+ *
+ * It is important to note that if you create a GtkEditable that uses a delegate,
+ * the low level #GtkEditable::insert-text and #GtkEditable::delete-text signals
+ * will be propagated from the "wrapper" editable to the delegate, but they will
+ * not be propagated from the delegate to the "wrapper" editable, as they would
+ * cause an infinite recursion. If you wish to connect to the #GtkEditable::insert-text
+ * and #GtkEditable::delete-text signals, you will need to connect to them on
+ * the delegate obtained via gtk_editable_get_delegate().
  */
 
 #include "config.h"