Clarify behavior of forward-comment.

1 files changed, 12 insertions, 4 deletions

diff --git a/lispref/syntax.texi b/lispref/syntax.texi
index e4c0384ccff..1135ff14d34 100644
--- a/lispref/syntax.texi
+++ b/lispref/syntax.texi
@@ -769,10 +769,18 @@ You can use @code{forward-comment} to move forward or backward over
 one comment or several comments.
 
 @defun forward-comment count
-This function moves point forward across @var{count} comments (backward,
-if @var{count} is negative).  If it finds anything other than a comment
-or whitespace, it stops, leaving point at the place where it stopped.
-It also stops after satisfying @var{count}.
+This function moves point forward across @var{count} complete comments
+(that is, including the starting delimiter and the terminating
+delimiter if any).  It moves backward if @var{count} is negative.  If
+it encounters anything other than a comment or whitespace, it stops,
+leaving point at the place where it stopped.  This includes (for
+instance) finding the end of a comment when moving forward and
+expecting the beginning of one.  The function also stops immediately
+after moving over the specified number of complete comments.
+
+This function cannot tell whether the ``comments'' it traverses are
+embedded within a string.  If they look like comments, it treats them
+as comments.
 @end defun
 
 To move forward over all comments and whitespace following point, use