bug#19461: 25.0.50; doc of `display-buffer-*' functions that take ALIST arg

[martin rudalics <rudalics@gmx.at>]

 > I think the docstrings must tell that.  Because the names suggest the
 > opposite.  Something like "this function is for internal use only

Readers might then ask why it does not use the "--" notation.

 > - it
 > is valid as an action function in the ALIST argument of
 > display-buffer

'display-buffer' calls it ACTION argument.  A problem with this is
that so far we do not specify what a "valid" action function is.

 > ...don't call it directly" or so?

A possible text would be:

"This is an action function for buffer display.  It should be called
only by 'display-buffer' or a function directly or indirectly called
by the latter."

Or with a reference to the Elisp manual:

"This is an action function for buffer display, see Info node `(elisp)
Buffer Display Action Functions'.  It should be called only by
'display-buffer' or a function directly or indirectly called by the
latter."

 > Problematic in this regard is that there _are_ other functions like that
 > that are not internal AFAIK - `pop-to-buffer' for example.  How can one
 > distinguish them?

I see no problems since these would not provide such an explanation.

martin