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

[Alan Mackenzie]

Miles Bader <miles@gnu.org> wrote on Sun, 25 Nov 2001 03:16:19 GMT:
> none@example.invalid (Alan Mackenzie) writes:
>> 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 find it hard to believe that anyone would think otherwise -- almost
> all `relative movement' commands work that way, using only local
> context to do their work (and indeed, doing otherwise doesn't seem to
> make much sense in this case).

I haven't been programming Emacs long enough to absorb this implicit
principle.

> Perhaps if you would give some idea of how you _thought_ it should
> work, it would clarify things...

When I read "this function moves point forward across COUNT comments" I
expected just that.  I.e. across things which _are_ comments, not things
which look like comments but aren't.  Font lock, for example, seems to
make this distinction.

Now the description implies that if forward-comment can't move across
COUNT comments, it will move over as many comments as possible up to that
number.  Therefore I also expected it would move over "half" a comment,
i.e. move from inside a comment to its beginning/end.  For example, I
would have expected (forward-comment -1) to move backwards over a C++
comment when point is at the end of the line:
// C++ comment
              ^ point

Come to think of it, (forward-comment 1) will move over "half" of a
comment at the end of (the accessible portion of) the buffer, and this
also renders my suggested "_complete_ comments" inaccurate.  :-(

Here's another version which might be more accurate and more readable:

> - Function: forward-comment count
>     This function moves point forward across COUNT comments and any
>     preceding or intervening whitespace (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.  Note that forward-comment
>     will only regard text as a comment if it sees an appropriate
>     comment delimiter at the buffer position it is currently examining,
>     and does so even if that text is within a string.

I'm not trying to be a bloody-minded pedant here.  The previous
paragraphs are an introspective analysis of what I subconsciously gleaned
from the info page.  

> While it's good to have comments be precise, it's also desirable to
> avoid bloating them unnecessarily.

Yes, I understand this.  But as somebody relatively new to elisp
programming, I think more precision is called for in this particular
case.

> -Miles

-- 
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").