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

[martin rudalics]

>> The doc strings say nothing about parameter ALIST, which in many cases
>> is the most important parameter.
>>
>> One can guess that it is an alist.  And one can guess, for the doc
>> strings that mention `inhibit-switch-frame' or
>> `pop-up-frame-parameters', that one or more of its entries can have such
>> a key, but that's all.  No guessing helps for
>> `display-buffer-(below-selected|at-bottom|in-previous-window|
>> use-some-window|no-window|same-window|assq-regexp)'.  Likewise, some of
>> the "internal" functions.
>
> It is indeed pretty obscure what ALIST is.

This problem is with us since day one of that buffer display code.
It's probably due to the fact that the 'display-buffer-*' functions
are inherently internal but never have been marked as such in order to
describe them in the manual and allow users to add new ones.

> Some of the functions say
> things like
>
> ---
> If ALIST contains a ’window-min-height’ entry, this function
> ensures that the window used is or can become at least as high as
> specified by that entry’s value.
> ---
>
> but looking at the code, it passes ALIST around a lot.  So is ALIST a
> general buffer/window property thing?

> At least one of these doc strings
> should say what it is, and the rest could refer to it.

Saying what it is is non-trivial, see section 28.13.3 of the Elisp
manual.  So I have no good idea how to do what you propose.

martin