forward-comment doesn't (quite) match its documentation

[Alan Mackenzie]

Emacs 21.1

The description of forward-comment in the elisp manual states:
> - Function: forward-comment count
>     This function moves point forward across COUNT comments (backward,
>     if 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 COUNT.
The documentation string is similar.

However, forward-comment will happily skip over a portion of a string (in
either direction) if it looks like a comment.  e.g. (in C mode):

void main (void)
{
    printf ("C comments look like this: /* comment */") ;
}

(with point just before "/*" or just after "*/").

I think the docs in the elisp manual and the documentation string could
be more precise about this.

I think it would also be a good idea to say something like "This function
moves point forward across COUNT _complete_ comments", since if point is
already within a comment, forward-comment will move point over neither
the head nor tail of it.

I would suggest something like the following for the elisp manual:
> - Function: forward-comment count

>     This function moves point forward across COUNT complete comments
>     (backward, if COUNT is negative).  If it finds anything other than
>     a comment delimiter or whitespace whilst scanning for a complete
>     comment, it stops, leaving point at the place where it stopped.  No
>     check is made of whether the "comments" moved over are embedded
>     within a string.  Note that the function also stops after
>     satisfying COUNT.

Or are these things bugs in forward-comment's implementation?

-- 
Alan Mackenzie (Munich, Germany)
Email: aacm@muuc.dee; to decode, wherever there is a repeated letter
(like "aa"), remove half of them (leaving, say, "a").