--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -2534,6 +2534,24 @@ nr2char({expr} [, {utf8}])	String	single
 or({expr}, {expr})		Number	bitwise OR
 pathshorten({expr})		String	shorten directory names in a path
 perleval({expr})		any	evaluate |Perl| expression
+popup_atcursor({what}, {options}) Number create popup window near the cursor
+popup_clear()			none	close all popup windows
+popup_close({id} [, {result}])	none	close popup window {id}
+popup_create({what}, {options}) Number	create a popup window
+popup_dialog({what}, {options}) Number	create a popup window used as a dialog
+popup_filter_menu({id}, {key})  Number	filter for a menu popup window
+popup_filter_yesno({id}, {key}) Number	filter for a dialog popup window
+popup_getoptions({id})		Dict	get options of popup window {id}
+popup_getpos({id})		Dict	get position of popup window {id}
+popup_hide({id})		none	hide popup menu {id}
+popup_menu({what}, {options})	Number	create a popup window used as a menu
+popup_move({id}, {options})	none	set position of popup window {id}
+popup_notification({what}, {options})
+				Number	create a notification popup window
+popup_show({id})		none	unhide popup window {id}
+popup_setoptions({id}, {options})
+				none	set options for popup window {id}
+popup_settext({id}, {text})	none	set the text of popup window {id}
 pow({x}, {y})			Float	{x} to the power of {y}
 prevnonblank({lnum})		Number	line nr of non-blank line <= {lnum}
 printf({fmt}, {expr1}...)	String	format text
@@ -7035,6 +7053,10 @@ perleval({expr})					*perleval()*
 <			[1, 2, 3, 4]
 		{only available when compiled with the |+perl| feature}
 
+
+popup_ functions are documented here: |popup-functions|.
+
+
 pow({x}, {y})						*pow()*
 		Return the power of {x} to the exponent {y} as a |Float|.
 		{x} and {y} must evaluate to a |Float| or a |Number|.

--- a/runtime/doc/popup.txt
+++ b/runtime/doc/popup.txt
@@ -1,16 +1,26 @@
-*popup.txt*  For Vim version 8.1.  Last change: 2019 Jun 30
+*popup.txt*  For Vim version 8.1.  Last change: 2019 Jul 04
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
 
 
-Displaying text in floating window.			*popup* *popup-window*
+Displaying text in a floating window.			*popup* *popup-window*
 
-THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE
 
 1. Introduction			|popup-intro|
+   Window position and size	|popup-position|
+   Closing the popup window	|popup-close|
+   Popup buffer and window	|popup-buffer|
 2. Functions			|popup-functions|
-3. Examples			|popup-examples|
+   Details			|popup-function-details|
+3. Usage			|popup-usage|
+   popup_create() arguments	|popup_create-arguments|
+   Popup text properties	|popup-props|
+   Popup filter			|popup-filter|
+   Popup callback		|popup-callback|
+   Popup scrollbar		|popup-scrollbar|
+   Popup mask			|popup-mask|
+4. Examples			|popup-examples|
 
 
 {not available if the |+textprop| feature was disabled at compile time}
@@ -55,7 +65,7 @@ If this is not what you are looking for,
 - balloon, see |balloon-eval|
 
 
-WINDOW POSITION AND SIZE			*popup-position*
+WINDOW POSITION AND SIZE				*popup-position*
 
 The height of the window is normally equal to the number of, possibly
 wrapping, lines in the buffer.  It can be limited with the "maxheight"
@@ -85,7 +95,7 @@ That way you can still see where it is, 
 that it is in.
 
 
-CLOSING THE POPUP WINDOW			*popup-close*
+CLOSING THE POPUP WINDOW				*popup-close*
 
 Normally the plugin that created the popup window is also in charge of closing
 it.  If somehow a popup hangs around, you can close all of them with: >
@@ -97,40 +107,41 @@ or by clicking anywhere inside the popup
 "close" property.  It is set by default for notifications.
 
 
-TODO:
-- Add test for when popup with mask is off the left and off the right of the
-  screen.
-- check padding/border when popup is off the left and right of the screen.
-- Have a way to scroll to the bottom? (#4577)
-- Why does 'nrformats' leak from the popup window buffer???
-- Disable commands, feedkeys(), CTRL-W, etc. in a popup window.
-  Use ERROR_IF_POPUP_WINDOW for more commands.
-- Add 'balloonpopup': instead of showing text, let the callback open a popup
-  window and return the window ID.   The popup will then be closed when the
-  mouse moves, except when it moves inside the popup.
-- For the "moved" property also include mouse movement?
-- Can the buffer be re-used, to avoid using up lots of buffer numbers?
-- Have an option to attach the popup to a text position, like text properties
-  do. (#4560)
-- Make redrawing more efficient and avoid flicker:
-    - put popup menu also put in popup_mask?
-- Invoke filter with character before mapping?
-- Figure out the size and position better.
-    if wrapping splits a double-wide character
-    if wrapping inserts indent
-- When drawing on top half a double-wide character, display ">" or "<" in the
-  incomplete cell.
-- Use a popup window for the "info" item of completion instead of using a
-  preview window.  Ideas in issue #4544.
-  How to add highlighting?
-- Implement:
-	flip option
+POPUP BUFFER AND WINDOW					*popup-buffer*
+
+If a popup function is called to create a popup from text, a new buffer is
+created to hold the text and text properties of the popup window.  The buffer
+is always associated with the popup window and manipulation is restricted:
+- the buffer has no name
+- 'buftype' is "popup"
+- 'swapfile' is off
+- 'bufhidden' is "hide"
+- 'buflisted' is off
+- 'undolevels' is -1: no undo at all
+- all other buffer-local and window-local options are set to their Vim default
+  value.
+
+It is possible to change the specifically mentioned options, but anything
+might break then, so better leave them alone.
+
+The window does have a cursor position, but the cursor is not displayed.
+
+To execute a command in the context of the popup window and buffer use
+`win_execute()`.  Example: >
+	call win_execute(winid, 'syntax enable')
+
+Options can be set on the window with `setwinvar()`, e.g.: >
+	call setwinvar(winid, '&wrap', 0)
+And options can be set on the buffer with `setbufvar()`, e.g.: >
+	call setbufvar(winbufnr(winid), '&filetype', 'java')
+Note that this does not trigger autocommands.  Use `win_execute()` if you do
+need them.
+
+
 
 ==============================================================================
 2. Functions						*popup-functions*
 
-THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE
-
 Creating a popup window:
 	|popup_create()|	centered in the screen
 	|popup_atcursor()|	just above the cursor position, closes when
@@ -159,9 +170,9 @@ Other:
 	|popup_getpos()|	get actual position and size of a popup
 
 
-[functions help to be moved to eval.txt later]
+DETAILS						*popup-function-details*
 
-popup_atcursor({what}, {options})			 *popup_atcursor()*
+popup_atcursor({what}, {options})			*popup_atcursor()*
 		Show the {what} above the cursor, and close it when the cursor
 		moves.  This works like: >
 			call popup_create({what}, {
@@ -199,7 +210,7 @@ popup_create({what}, {options})				*popu
 		the popup closes.
 
 		{options} is a dictionary with many possible entries.
-		See |popup_create-usage| for details.
+		See |popup_create-arguments| for details.
 
 		Returns a window-ID, which can be used with other popup
 		functions.  Use `winbufnr()` to get the number of the buffer
@@ -417,38 +428,10 @@ popup_settext({id}, {text})				*popup_se
 		by the different text.
 
 
-POPUP BUFFER AND WINDOW					*popup-buffer*
-
-A new buffer is created to hold the text and text properties of the popup
-window.  The buffer is always associated with the popup window and
-manipulation is restricted:
-- the buffer has no name
-- 'buftype' is "popup"
-- 'swapfile' is off
-- 'bufhidden' is "hide"
-- 'buflisted' is off
-- 'undolevels' is -1: no undo at all
-- all other buffer-local and window-local options are set to their Vim default
-  value.
+==============================================================================
+3. Usage						*popup-usage*
 
-It is possible to change the specifically mentioned options, but anything
-might break then, so better leave them alone.
-
-The window does have a cursor position, but the cursor is not displayed.
-
-To execute a command in the context of the popup window and buffer use
-`win_execute()`.  Example: >
-	call win_execute(winid, 'syntax enable')
-
-Options can be set on the window with `setwinvar()`, e.g.: >
-	call setwinvar(winid, '&wrap', 0)
-And options can be set on the buffer with `setbufvar()`, e.g.: >
-	call setbufvar(winbufnr(winid), '&filetype', 'java')
-Note that this does not trigger autocommands.  Use `win_execute()` if you do
-need them.
-
-
-POPUP_CREATE() ARGUMENTS				*popup_create-usage*
+POPUP_CREATE() ARGUMENTS			 *popup_create-arguments*
 
 The first argument of |popup_create()| (and the second argument to
 |popup_settext()|) specifies the text to be displayed, and optionally text
@@ -709,9 +692,9 @@ To make the four corners transparent:
 	[[1, 1, 1, 1], [-1, -1, 1, 1], [1, 1, -1, -1], [-1, -1, -1, -1]]
 
 ==============================================================================
-3. Examples						*popup-examples*
+4. Examples						*popup-examples*
 
-TODO
+TODO: more interesting examples
 					*popup_dialog-example*
 Prompt the user to press y/Y or n/N: >
 

--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -1,4 +1,4 @@
-*usr_41.txt*	For Vim version 8.1.  Last change: 2019 Jun 09
+*usr_41.txt*	For Vim version 8.1.  Last change: 2019 Jul 04
 
 		     VIM USER MANUAL - by Bram Moolenaar
 
@@ -748,6 +748,12 @@ Working with text in the current buffer:
 	getcharsearch()		return character search information
 	setcharsearch()		set character search information
 
+Working with text in another buffer:
+	getbufline()		get a list of lines from the specified buffer
+	setbufline()		replace a line in the specified buffer
+	appendbufline()		append a list of lines in the specified buffer
+	deletebufline()		delete lines from a specified buffer
+
 					*system-functions* *file-functions*
 System functions and manipulation of files:
 	glob()			expand wildcards
@@ -799,8 +805,10 @@ Buffers, windows and the argument list:
 	argidx()		current position in the argument list
 	arglistid()		get id of the argument list
 	argv()			get one entry from the argument list
+	bufadd()		add a file to the list of buffers
 	bufexists()		check if a buffer exists
 	buflisted()		check if a buffer exists and is listed
+	bufload()		ensure a buffer is loaded
 	bufloaded()		check if a buffer exists and is loaded
 	bufname()		get the name of a specific buffer
 	bufnr()			get the buffer number of a specific buffer
@@ -811,10 +819,6 @@ Buffers, windows and the argument list:
 	bufwinid()		get the window ID of a specific buffer
 	bufwinnr()		get the window number of a specific buffer
 	winbufnr()		get the buffer number of a specific window
-	getbufline()		get a list of lines from the specified buffer
-	setbufline()		replace a line in the specified buffer
-	appendbufline()		append a list of lines in the specified buffer
-	deletebufline()		delete lines from a specified buffer
 	listener_add()		add a callback to listen to changes
 	listener_flush()	invoke listener callbacks
 	listener_remove()	remove a listener callback
@@ -1038,6 +1042,25 @@ Terminal window:				*terminal-functions*
 	term_setrestore()	set command to restore a terminal
 	term_setsize()		set the size of a terminal
 
+Popup window:					*popup-window-functions*
+	popup_create()		create popup centered in the screen
+	popup_atcursor()	create popup just above the cursor position,
+				closes when the cursor moves away
+	popup_notification()	show a notification for three seconds
+	popup_dialog()		create popup centered with padding and border
+	popup_menu()		prompt for selecting an item from a list
+	popup_hide()		hide a popup temporarily
+	popup_show()		show a previously hidden popup
+	popup_move()		change the position and size of a popup
+	popup_setoptions()	override options of a popup
+	popup_settext()		replace the popup buffer contents
+	popup_close()		close one popup
+	popup_clear()		close all popups
+	popup_filter_menu()	select from a list of items
+	popup_filter_yesno()	blocks until 'y' or 'n' is pressed
+	popup_getoptions()	get current options for a popup
+	popup_getpos()		get actual position and size of a popup
+
 Timers:						*timer-functions*
 	timer_start()		create a timer
 	timer_pause()		pause or unpause a timer

--- a/src/version.c
+++ b/src/version.c
@@ -778,6 +778,8 @@ static char *(features[]) =
 static int included_patches[] =
 {   /* Add new patch number below this line */
 /**/
+    1628,
+/**/
     1627,
 /**/
     1626,