emacs-27 fd1fe1e: Add doc to syntax-propertize-function saying it must do a 100% job

[Alan Mackenzie]

branch: emacs-27
commit fd1fe1e1ecb6c68bbdea4bf071166779388174d0
Author: Alan Mackenzie <acm@muc.de>
Commit: Alan Mackenzie <acm@muc.de>

    Add doc to syntax-propertize-function saying it must do a 100% job
    
    and cannot be combined with other ways of applying syntax-table text
    properties.
    
    * lisp/emacs-lisp/syntax.el (syntax-propertize-function): Amend doc string.
    
    * doc/lispref/syntax.texi (Syntax Properties): Amend the description of the
    variable.
---
 doc/lispref/syntax.texi   | 9 +++++++++
 lisp/emacs-lisp/syntax.el | 7 ++++++-
 2 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi
index 9eb99a0..b3c7766 100644
--- a/doc/lispref/syntax.texi
+++ b/doc/lispref/syntax.texi
@@ -575,6 +575,15 @@ position before @var{end}.  However, it should not call
 @code{syntax-ppss-flush-cache}; so, it is not allowed to call
 @code{syntax-ppss} on some position and later modify the buffer at an
 earlier position.
+
+@strong{Caution:} When this variable is non-@code{nil}, Emacs removes
+@code{syntax-table} text properties arbitrarily and relies on
+@code{syntax-propertize-function} to reapply them.  Thus if this
+facility is used at all, the function must apply @strong{all}
+@code{syntax-table} text properties used by the major mode.  In
+particular, Modes derived from a CC Mode mode must not use this
+variable, since CC Mode uses other means to apply and remove these
+text properties.
 @end defvar
 
 @defvar syntax-propertize-extend-region-functions
diff --git a/lisp/emacs-lisp/syntax.el b/lisp/emacs-lisp/syntax.el
index 11cc198..f4f0772 100644
--- a/lisp/emacs-lisp/syntax.el
+++ b/lisp/emacs-lisp/syntax.el
@@ -65,7 +65,12 @@ cannot be handled just by the buffer's syntax-table.
 The specified function may call `syntax-ppss' on any position
 before END, but it should not call `syntax-ppss-flush-cache',
 which means that it should not call `syntax-ppss' on some
-position and later modify the buffer on some earlier position.")
+position and later modify the buffer on some earlier position.
+
+Note: When this variable is a function, it must apply _all_ the
+`syntax-table' properties needed in the given text interval.
+Using both this function and other means to apply these
+properties won't work properly.")
 
 (defvar syntax-propertize-chunk-size 500)