font-lock and FACENAME eval: doc (+API)

[JD Smith]

Especially now with treesitter, there are many examples where font-lock would be a good solution to a problem, but you want to do more than just apply faces to text.  You may want to alter 'display properties, hide regions, add other embellishments, etc.  I've long noticed a usage of the font-lock API that seems to go nearly unmentioned in the docs, and which I've used myself (highlight added):

MATCH-HIGHLIGHT should be of the form:

 (SUBEXP FACENAME [OVERRIDE [LAXMATCH]])

SUBEXP is the number of the subexpression of MATCHER to be

highlighted.

[FACENAME is an _expression_ whose value is the face to use.]

Instead of a face, FACENAME can evaluate to a property list of

the form (face FACE PROP1 VAL1 PROP2 VAL2 ...)  in which case all

the listed text-properties will be set rather than just FACE. 

You'll often find font-lock-keywords with the following form (here from org-modern):

   `((,org-list-full-item-re (3 (org-modern--checkbox) nil t))))

Here FACENAME = (org-modern--checkbox).  This just delegates all the work of setting text properties on the associated text to the FACENAME form, which evals a function call. 

This raises a few issues;

i) Is it not inefficient to evaluate (some-func) vs. calling it directly in performane-sensitive font-locking code?

ii) Should this behavior be documented in some way?  I was endlessly confused by this common pattern when I was studying font-lock, since the docs do not allude to it at all. 

ii) If not, should some explicit hook functionality be added to font-lock's API, to open up for other uses its exceptional ability to treat only the text in need of updating?