Inadequate description of FUNCTION in elisp font-lock info page

[Alan Mackenzie]

In the elisp info page "Search-based Fontification" the description of
FUNCTION is this:

`FUNCTION'
     Find text by calling FUNCTION, and highlight the matches it finds
     using `font-lock-keyword-face'.

     When FUNCTION is called, it receives one argument, the limit of
     the search.  It should return non-`nil' if it succeeds, and set the
     match data to describe the match that was found.

I had to look at font-lock.el to work out the complete interface to such
a FUNCTION.  What is missing from the above description is a statement of
how point is to be changed.  It is also not clear, at first reading, that
FUNCTION gets called repeatedly.  I propose the following as an
improvement of the second paragraph:

     When FUNCTION is called, it receives one argument, the limit of the
     search.  Its search should start at point and not extend beyond the
     limit.  FUNCTION should return non-`nil' if it succeeds, and set the
     match data to describe the match that was found.  FUNCTION will be
     called repeatedly with the same limit, and with point where the
     previous invocation left it, until it fails.  It need not reset
     point to a sensible value on failure.

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