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

[martin rudalics]

> 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