bug#33870: 27.0.50; xref-goto-xref not configurable

[Drew Adams]

> The 'display-buffer--maybe-' functions are macros in disguise invented
> by Chong to simplify coding the rest.  Unless we can't avoid it, I
> would not make them public because then we would have to (1) document
> them, (2) explain the semantics of the "maybe" and (3) justify why the
> remaining 'display-buffer--maybe-' functions are not public.

_Everything_ in Emacs is (and should be) public.

Why would Emacs users not deserve all of #1, #2,
and #3?

Wouldn't you make that info available to Emacs
developers?  How are Emacs users different from
Emacs developers with regard to what info they
deserve to know about, including design and
implementation behavior and their reasons?

Many users might not be interested in digging
into such info, but why hide it?  Please consider
instead making such info clear and explicit for
everyone.

An absolute minimum in this regard is comments
in the code.

But Emacs has doc strings, and beyond design
and implementation information we should
document function behavior in doc strings.
It should make no difference how tentative or
temporary or "internal" we might currently
think some function is - its behavior deserves
to be documented.

"Unless we can't avoid it...".  We should not
avoid it or anything like it.  It should be a
moral imperative, as well as a question of
helpfulness and civility, for Emacs to document
itself to users.