lua: docs and tests for vim.schedule

runtime/doc/api.txt

@@ -203,6 +203,8 @@ User reloads the buffer with ":edit", emits: >
 In-process lua plugins can also recieve buffer updates, in the form of lua
 callbacks. These callbacks are called frequently in various contexts, buffer
 contents or window layout should not be changed inside these |textlock|.
+|lua-vim.schedule| can be used to defer these operations to the main loop,
+where they are allowed.
 
 |nvim_buf_attach| will take keyword args for the callbacks. "on_lines" will
 receive parameters ("lines", {buf}, {changedtick}, {firstline}, {lastline}, {new_lastline}).

runtime/doc/if_lua.txt

@@ -379,6 +379,12 @@ vim.stricmp(a, b)					*lua-vim.stricmp*
 	string arguments and returns 0, 1 or -1 if strings are equal, a is 
 	greater then b or a is lesser then b respectively.
 
+vim.schedule(callback)					*lua-vim.schedule*
+	Schedule `callback` to be called soon by the main event loop. This is
+        useful in contexts where some functionality is blocked, like an
+        autocommand or callback running with |textlock|. Then the scheduled
+        callback could invoke this functionality later when it is allowed.
+
 vim.type_idx						*lua-vim.type_idx*
 	Type index for use in |lua-special-tbl|.  Specifying one of the 
 	values from |lua-vim.types| allows typing the empty table (it is