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.

2 files changed, 15 insertions, 1 deletions

diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi
index 9eb99a0ac92..b3c77665bae 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 11cc1988b1f..f4f077264be 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)