bug#60168: 28.2; Doc string of `face-spec-recalc'

[Eli Zaretskii]

tags 60168 notabug wontfix
close 60168
thanks

> From: Drew Adams <drew.adams@oracle.com>
> Date: Sat, 17 Dec 2022 20:57:48 +0000
> 
> I don't understand this doc string.

You aren't supposed to, unless you are hacking on the face-related
code (in which case the doc string is crystal clear).

> And lest someone claim that this is just a "helper" function or
> "internal": this is the meat of what `face-spec-set' does.  If this
> isn't described here then it should be described for `face-spec-set'.

face-spec-set has its own doc string that explains what it does.  Its
doc string doesn't reference face-spec-recalc.  The "meat" you mention
is basically internal implementation details of how face spec is
calculated and applied, something that doesn't belong to doc strings.

If you have specific questions needed to understand how to define and
use faces in Lisp programs, please ask those specific questions
(probably in another thread).  Or if you have specific questions
regarding the face implementation and face spec (re-)calculation,
please ask specific questions on emacs-devel.

> (And in any case, the doc string here needs to be fixed or removed.)

I disagree.

There's no bug here that I can see.

Closing.