1 files changed, 11 insertions, 8 deletions
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 0c3c497533..bc89ffefe6 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -56,11 +56,12 @@ void nvim_command(String command, Error *err)
   try_end(err);
 }
 
-/// Retrieves highlight description from its name
+/// Gets a highlight definition by name.
 ///
 /// @param name Highlight group name
-/// @param rgb True to export GUI values
-/// @return a highlight description e.g. {'bold': true, 'bg': 123, 'fg': 42}
+/// @param rgb Export RGB colors
+/// @param[out] err Error details, if any
+/// @return Highlight definition map
 /// @see nvim_get_hl_by_id
 Dictionary nvim_get_hl_by_name(String name, Boolean rgb, Error *err)
   FUNC_API_SINCE(3)
@@ -69,7 +70,7 @@ Dictionary nvim_get_hl_by_name(String name, Boolean rgb, Error *err)
   int id = syn_name2id((const char_u *)name.data);
 
   if (id == 0) {
-    api_set_error(err, kErrorTypeException, "Invalid highlight name %s",
+    api_set_error(err, kErrorTypeException, "Invalid highlight name: %s",
                   name.data);
     return result;
   }
@@ -77,17 +78,19 @@ Dictionary nvim_get_hl_by_name(String name, Boolean rgb, Error *err)
   return result;
 }
 
-/// Retrieves highlight description from its id
+/// Gets a highlight definition by id. |hlID()|
 ///
-/// @param hl_id highlight id as returned by |hlID()|
-/// @param rgb True to export GUI values
+/// @param hl_id Highlight id as returned by |hlID()|
+/// @param rgb Export RGB colors
+/// @param[out] err Error details, if any
+/// @return Highlight definition map
 /// @see nvim_get_hl_by_name
 Dictionary nvim_get_hl_by_id(Integer hl_id, Boolean rgb, Error *err)
   FUNC_API_SINCE(3)
 {
   Dictionary dic = ARRAY_DICT_INIT;
   if (syn_get_final_id((int)hl_id) == 0) {
-    api_set_error(err, kErrorTypeException, "Invalid highlight id %d", hl_id);
+    api_set_error(err, kErrorTypeException, "Invalid highlight id: %d", hl_id);
     return dic;
   }
   int attrcode = syn_id2attr((int)hl_id);