Improve documentation of self-insert-uses-region-functions

* lisp/simple.el (self-insert-uses-region-functions): Clarify the
doc string.
* lisp/delsel.el (delete-selection-uses-region-p): Mention
'self-insert-command' in the doc string.  (Bug#29373)

* doc/lispref/text.texi (Commands for Insertion): Mention
'self-insert-uses-region-functions'.
* doc/lispref/modes.texi (Keymaps and Minor Modes): Add a
cross-reference to "Commands for Insertion".

1 files changed, 9 insertions, 3 deletions

diff --git a/lisp/delsel.el b/lisp/delsel.el
index 17b46efc7cb..65b2cb85cea 100644
--- a/lisp/delsel.el
+++ b/lisp/delsel.el
@@ -256,12 +256,18 @@ See `delete-selection-helper'."
                                   (get this-command 'delete-selection)))))
 
 (defun delete-selection-uses-region-p ()
-  "Return t when the current command will be using the region
-rather than having `delete-selection' delete it, nil otherwise.
+  "Return t when `delete-selection-mode' should not delete the region.
+
+The `self-insert-command' could be the current command or may be
+called by the current command.  If this function returns nil,
+then `delete-selection' is allowed to delete the region.
 
 This function is intended for use as the value of the
 `delete-selection' property of a command, and shouldn't be used
-for anything else."
+for anything else.  In particular, `self-insert-command' has this
+function as its `delete-selection' property, so that \"electric\"
+self-insert commands that act on the region could adapt themselves
+to `delete-selection-mode'."
   (not (run-hook-with-args-until-success
         'self-insert-uses-region-functions)))