Document c-guess-basic-syntax in the CC Mode manual.

* doc/misc/cc-mode.texi (Syntactic Analysis): Document the function, adding
pxrefs to Custom Line-Up and Other Indentation.
(Custom Line-Up): Add a note on using c-guess-basic-syntax with a pxref to
Syntactic Analysis.

1 files changed, 18 insertions, 3 deletions

diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi
index bc8d24fd992..459369ed9c4 100644
--- a/doc/misc/cc-mode.texi
+++ b/doc/misc/cc-mode.texi
@@ -3887,9 +3887,19 @@ of the variables associated with indentation, not even
 @cindex syntactic element
 @cindex syntactic context
 The first thing @ccmode{} does when indenting a line of code, is to
-analyze the line, determining the @dfn{syntactic context} of the
-(first) construct on that line.  It's a list of @dfn{syntactic
-elements}, where each syntactic element in turn is a list@footnote{In
+analyze the line by calling @code{c-guess-basic-syntax}, determining
+the syntactic context of the (first) construct on that line.  Although
+this function is mainly used internally, it can sometimes be useful in
+Line-up functions (@pxref{Custom Line-Up}) or in functions on
+@code{c-special-indent-hook} (@pxref{Other Indentation}).
+
+@defun c-guess-basic-syntax
+@findex guess-basic-syntax (c-)
+Determine the syntactic context of the current line.
+@end defun
+
+The @dfn{syntactic context} is a list of @dfn{syntactic elements},
+where each syntactic element in turn is a list@footnote{In
 @ccmode 5.28 and earlier, a syntactic element was a dotted pair; the
 cons was the syntactic symbol and the cdr was the anchor position.
 For compatibility's sake, the parameter passed to a line-up function
@@ -6553,6 +6563,11 @@ only meaningful when used on syntactic elements taken from
 @code{c-syntactic-element} or @code{c-syntactic-context}.
 @end defun
 
+Sometimes you may need to use the syntactic context of a line other
+than the one being indented.  You can determine this by (temporarily)
+moving point onto this line and calling @code{c-guess-basic-syntax}
+(@pxref{Syntactic Analysis}).
+
 Custom line-up functions can be as simple or as complex as you like, and
 any syntactic symbol that appears in @code{c-offsets-alist} can have a
 custom line-up function associated with it.