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

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> 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.  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.

I've Cc'd Martin.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no