4 files changed, 14 insertions, 26 deletions
diff --git a/src/nvim/api/ui.c b/src/nvim/api/ui.c
index 573be23d8e..bbbd5ab2dc 100644
--- a/src/nvim/api/ui.c
+++ b/src/nvim/api/ui.c
@@ -215,6 +215,7 @@ static void ui_set_option(UI *ui, String name, Object value, Error *error)
 #undef UI_EXT_OPTION
 }
 
+/// Pushes data into UI.UIData, to be consumed later by remote_ui_flush().
 static void push_call(UI *ui, char *name, Array args)
 {
   Array call = ARRAY_DICT_INIT;
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index cfbe34b848..ab893a4c0f 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -255,12 +255,11 @@ free_vim_args:
   return rv;
 }
 
-/// Execute lua code. Parameters might be passed, they are available inside
-/// the chunk as `...`. The chunk can return a value.
+/// Execute lua code. Parameters (if any) are available as `...` inside the
+/// chunk. The chunk can return a value.
 ///
-/// To evaluate an expression, it must be prefixed with "return ". For
-/// instance, to call a lua function with arguments sent in and get its
-/// return value back, use the code "return my_function(...)".
+/// Only statements are executed. To evaluate an expression, prefix it
+/// with `return`: return my_function(...)
 ///
 /// @param code       lua code to execute
 /// @param args       Arguments to the code
@@ -423,29 +422,18 @@ void nvim_del_var(String name, Error *err)
   dict_set_var(&globvardict, name, NIL, true, false, err);
 }
 
-/// Sets a global variable
-///
 /// @deprecated
-///
-/// @param name     Variable name
-/// @param value    Variable value
-/// @param[out] err Error details, if any
+/// @see nvim_set_var
 /// @return Old value or nil if there was no previous value.
-///
-///         @warning It may return nil if there was no previous value
-///                  or if previous value was `v:null`.
+/// @warning May return nil if there was no previous value
+///          OR if previous value was `v:null`.
 Object vim_set_var(String name, Object value, Error *err)
 {
   return dict_set_var(&globvardict, name, value, false, true, err);
 }
 
-/// Removes a global variable
-///
 /// @deprecated
-///
-/// @param name     Variable name
-/// @param[out] err Error details, if any
-/// @return Old value
+/// @see nvim_del_var
 Object vim_del_var(String name, Error *err)
 {
   return dict_set_var(&globvardict, name, NIL, true, true, err);
diff --git a/src/nvim/event/loop.c b/src/nvim/event/loop.c
index 570db6dfc3..5adf16c0f3 100644
--- a/src/nvim/event/loop.c
+++ b/src/nvim/event/loop.c
@@ -66,6 +66,7 @@ void loop_poll_events(Loop *loop, int ms)
 ///       means `fast_events` is NOT processed in an "editor mode"
 ///       (VimState.execute), so redraw and other side-effects are likely to be
 ///       skipped.
+/// @see loop_schedule_deferred
 void loop_schedule(Loop *loop, Event event)
 {
   uv_mutex_lock(&loop->mutex);
diff --git a/src/nvim/msgpack_rpc/channel.c b/src/nvim/msgpack_rpc/channel.c
index 02f3854f47..88232a55de 100644
--- a/src/nvim/msgpack_rpc/channel.c
+++ b/src/nvim/msgpack_rpc/channel.c
@@ -188,12 +188,11 @@ uint64_t channel_connect(bool tcp, const char *address, int timeout,
   return channel->id;
 }
 
-/// Sends event/arguments to channel
+/// Publishes an event to a channel.
 ///
-/// @param id The channel id. If 0, the event will be sent to all
-///        channels that have subscribed to the event type
-/// @param name The event name, an arbitrary string
-/// @param args Array with event arguments
+/// @param id Channel id. 0 means "broadcast to all subscribed channels"
+/// @param name Event name (application-defined)
+/// @param args Array of event arguments
 /// @return True if the event was sent successfully, false otherwise.
 bool channel_send_event(uint64_t id, const char *name, Array args)
 {
@@ -215,7 +214,6 @@ bool channel_send_event(uint64_t id, const char *name, Array args)
       send_event(channel, name, args);
     }
   }  else {
-    // TODO(tarruda): Implement event broadcasting in vimscript
     broadcast_event(name, args);
   }