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

[Drew Adams <drew.adams@oracle.com>]

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)