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

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

[Drew Adams]

I don't understand this doc string.

What is the meaning of the indented occurrences of `|'?

How is one supposed to read this?  Are there 3 sources?  5 sources? 6
sources?

Is `|' supposed to separate the sources (so there are only 3)?  If so,
how to understand the one that starts with `(theme...)' and ends with
`(X resources...)'?

Why are some things - which clearly are NOT code - in parens?  Of what
use are the parens here?  Why `(defface default spec)' (parens) but
`defface override spec' (no parens)?

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'.
(And in any case, the doc string here needs to be fixed or removed.)

In GNU Emacs 28.2 (build 2, x86_64-w64-mingw32)
 of 2022-09-13 built on AVALON
Windowing system distributor 'Microsoft Corp.', version 10.0.19044
System Description: Microsoft Windows 10 Pro (v10.0.2009.19044.2251)

Configured using:
 'configure --with-modules --without-dbus --with-native-compilation
 --without-compress-install CFLAGS=-O2'

Configured features:
ACL GIF GMP GNUTLS HARFBUZZ JPEG JSON LCMS2 LIBXML2 MODULES NATIVE_COMP
NOTIFY W32NOTIFY PDUMPER PNG RSVG SOUND THREADS TIFF TOOLKIT_SCROLL_BARS
XPM ZLIB

(NATIVE_COMP present but libgccjit not available)

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.