Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

>>> The only problematic modes are those with a large keymaps in the
>>> docstring. The argument doc paragraph ends up being outside the visible
>>> area on the screen which feels awkward. That said, I'm feel the benefit
>>> outweigh this awkwardness.
>
> Maybe we could add the paragraph at the first empty line (if there's
> one), instead of always at the end?

Sounds reasonable, I was hesitant to make the implementation more
complicated but it turns out not to be that bad. Attached the patch to
either append the paragraph or insert it at the first empty line.