doc [ci skip] #10129

- document lua vim.loop #10123

runtime/doc/api.txt

@@ -203,8 +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,
+|vim.schedule| can be used to defer these operations to the main loop, where
-where they are allowed.
+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/eval.txt

@@ -5532,7 +5532,7 @@ log10({expr})						*log10()*
 
 luaeval({expr}[, {expr}])
 		Evaluate Lua expression {expr} and return its result converted
-		to Vim data structures. See |lua-luaeval| for more details.
+		to Vim data structures. See |lua-eval| for more details.
 
 map({expr1}, {expr2})					*map()*
 		{expr1} must be a |List| or a |Dictionary|.

runtime/doc/if_lua.txt

@@ -258,8 +258,7 @@ position are restricted when the command is executed in the |sandbox|.
 
 
 ==============================================================================
-luaeval()						*lua-luaeval* *lua-eval*
+luaeval()						*lua-eval* *luaeval()*
-							*luaeval()*
 
 The (dual) equivalent of "vim.eval" for passing Lua values to Nvim is
 "luaeval". "luaeval" takes an expression string and an optional argument used 
@@ -371,41 +370,96 @@ For example, to use the "nvim_get_current_line()" API function, call
 
     print(tostring(vim.api.nvim_get_current_line()))
 
+------------------------------------------------------------------------------
+VIM.LOOP							*lua-loop*
+
+`vim.loop` exposes all features of the Nvim event-loop.  This is a lower-level
+API that provides functionality for networking, filesystem, and process
+management.
+
+See http://docs.libuv.org for complete documentation.
+See https://github.com/luvit/luv/tree/master/examples for examples.
+
+Example: repeating timer
+    1. Save this code to a file.
+    2. Execute it with ":luafile %". >
+
+    -- Create a timer handle (implementation detail: uv_timer_t).
+    local timer = vim.loop.new_timer()
+    local i = 0
+    -- Waits 1000ms, then repeats every 750ms until timer:close().
+    timer:start(1000, 750, function()
+      print('timer invoked! i='..tostring(i))
+      if i > 4 then
+        timer:close()  -- Always close handles to avoid leaks.
+      end
+      i = i + 1
+    end)
+    print('sleeping');
+
+
+Example: TCP echo-server				*tcp-server*
+    1. Save this code to a file.
+    2. Execute it with ":luafile %".
+    3. Note the port number.
+    4. Connect from any TCP client (e.g. "nc 0.0.0.0 36795"): >
+
+    local function create_server(host, port, on_connection)
+      local server = vim.loop.new_tcp()
+      server:bind(host, port)
+      server:listen(128, function(err)
+        assert(not err, err)  -- Check for errors.
+        local sock = vim.loop.new_tcp()
+        server:accept(sock)  -- Accept client connection.
+        on_connection(sock)  -- Start reading messages.
+      end)
+      return server
+    end
+    local server = create_server('0.0.0.0', 0, function(sock)
+      sock:read_start(function(err, chunk)
+        assert(not err, err)  -- Check for errors.
+        if chunk then
+          sock:write(chunk)  -- Echo received messages to the channel.
+        else  -- EOF (stream closed).
+          sock:close()  -- Always close handles to avoid leaks.
+        end
+      end)
+    end)
+    print('TCP echo-server listening on port: '..server:getsockname().port)
+
 ------------------------------------------------------------------------------
 VIM							*lua-util*
 
-vim.stricmp(a, b)					*lua-vim.stricmp*
+vim.stricmp({a}, {b})					*vim.stricmp()*
-	Function used for case-insensitive string comparison.  Takes two 
+        Compares strings case-insensitively.  Returns 0, 1 or -1 if strings
-	string arguments and returns 0, 1 or -1 if strings are equal, a is 
+        are equal, {a} is greater than {b} or {a} is lesser than {b},
-	greater then b or a is lesser then b respectively.
+        respectively.
 
-vim.schedule(callback)					*lua-vim.schedule*
+vim.schedule({callback})				*vim.schedule()*
-	Schedule `callback` to be called soon by the main event loop. This is
+        Schedules {callback} to be invoked soon by the main event-loop. Useful
-        useful in contexts where some functionality is blocked, like an
+        to avoid |textlock| or other temporary restrictions.
-        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*
+vim.type_idx						*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 
+	values from |vim.types| allows typing the empty table (it is 
 	unclear whether empty lua table represents empty list or empty array) 
 	and forcing integral numbers to be |Float|.  See |lua-special-tbl| for 
 	more details.
 
-vim.val_idx						*lua-vim.val_idx*
+vim.val_idx						*vim.val_idx*
 	Value index for tables representing |Float|s.  A table representing 
 	floating-point value 1.0 looks like this: >
             {
               [vim.type_idx] = vim.types.float,
               [vim.val_idx] = 1.0,
             }
-<	See also |lua-vim.type_idx| and |lua-special-tbl|.
+<	See also |vim.type_idx| and |lua-special-tbl|.
 
-vim.types						*lua-vim.types*
+vim.types						*vim.types*
-	Table with possible values for |lua-vim.type_idx|.  Contains two sets 
+	Table with possible values for |vim.type_idx|.  Contains two sets 
-	of key-value pairs: first maps possible values for |lua-vim.type_idx| 
+	of key-value pairs: first maps possible values for |vim.type_idx| 
 	to human-readable strings, second maps human-readable type names to 
-	values for |lua-vim.type_idx|.  Currently contains pairs for `float`, 
+	values for |vim.type_idx|.  Currently contains pairs for `float`, 
 	`array` and `dictionary` types.
 
 	Note: one must expect that values corresponding to `vim.types.float`, 

src/nvim/mbyte.c

@@ -456,43 +456,50 @@ static bool intable(const struct interval *table, size_t n_items, int c)
   return false;
 }
 
-/*
+/// For UTF-8 character "c" return 2 for a double-width character, 1 for others.
- * For UTF-8 character "c" return 2 for a double-width character, 1 for others.
+/// Returns 4 or 6 for an unprintable character.
- * Returns 4 or 6 for an unprintable character.
+/// Is only correct for characters >= 0x80.
- * Is only correct for characters >= 0x80.
+/// When p_ambw is "double", return 2 for a character with East Asian Width
- * When p_ambw is "double", return 2 for a character with East Asian Width
+/// class 'A'(mbiguous).
- * class 'A'(mbiguous).
+///
- */
+/// @note Tables `doublewidth` and `ambiguous` are generated by
+///       gen_unicode_tables.lua, which must be manually invoked as needed.
 int utf_char2cells(int c)
 {
   if (c >= 0x100) {
 #ifdef USE_WCHAR_FUNCTIONS
-    /*
+    //
-     * Assume the library function wcwidth() works better than our own
+    // Assume the library function wcwidth() works better than our own
-     * stuff.  It should return 1 for ambiguous width chars!
+    // stuff.  It should return 1 for ambiguous width chars!
-     */
+    //
     int n = wcwidth(c);
 
-    if (n < 0)
+    if (n < 0) {
-      return 6;                 /* unprintable, displays <xxxx> */
+      return 6;                 // unprintable, displays <xxxx>
-    if (n > 1)
+    }
+    if (n > 1) {
       return n;
+    }
 #else
-    if (!utf_printable(c))
+    if (!utf_printable(c)) {
-      return 6;                 /* unprintable, displays <xxxx> */
+      return 6;                 // unprintable, displays <xxxx>
-    if (intable(doublewidth, ARRAY_SIZE(doublewidth), c))
+    }
+    if (intable(doublewidth, ARRAY_SIZE(doublewidth), c)) {
       return 2;
+    }
 #endif
     if (p_emoji && intable(emoji_width, ARRAY_SIZE(emoji_width), c)) {
       return 2;
     }
+  } else if (c >= 0x80 && !vim_isprintc(c)) {
+    // Characters below 0x100 are influenced by 'isprint' option.
+    return 4;                   // unprintable, displays <xx>
   }
-  /* Characters below 0x100 are influenced by 'isprint' option */
-  else if (c >= 0x80 && !vim_isprintc(c))
-    return 4;                   /* unprintable, displays <xx> */
 
-  if (c >= 0x80 && *p_ambw == 'd' && intable(ambiguous, ARRAY_SIZE(ambiguous), c))
+  if (c >= 0x80 && *p_ambw == 'd'
+      && intable(ambiguous, ARRAY_SIZE(ambiguous), c)) {
     return 2;
+  }
 
   return 1;
 }

src/nvim/normal.c

@@ -7987,8 +7987,8 @@ static void nv_event(cmdarg_T *cap)
   multiqueue_process_events(main_loop.events);
   finish_op = false;
   if (may_restart) {
-    // Tricky: if restart_edit was set before the handler we are in ctrl-o mode
+    // Tricky: if restart_edit was set before the handler we are in ctrl-o mode,
-    // but if not, the event should be allow to trigger :startinsert
+    // but if not, the event should be allowed to trigger :startinsert.
     cap->retval |= CA_COMMAND_BUSY;  // don't call edit() now
   }
 }