bug#57087: 29.0.50; (face-at-point nil t) does not return all faces when hl-line-mode is active

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> This is a misunderstanding of what the doc string means when it says
> "faces".  It doesn't mean that you should see more than one face in
> the above situation.
>
> This is not a bug, it's just that your expectations from what
> face-at-point can do are incorrect.

Then I think this doc string needs clarification, at least:

---
face-at-point is a byte-compiled Lisp function in faces.el.

(face-at-point &optional THING MULTIPLE)

Return the face of the character after point.
If it has more than one face, return the first one.
If THING is non-nil try first to get a face name from the buffer.
IF MULTIPLE is non-nil, return a list of all faces.
Return nil if there is no face.
---

I think it sounds like it would be more useful if it did indeed return
all the faces at point instead of just the face(s) from either the
overlay or the face(s) from the text property.